Circuit objects

class quantumflow.Circuit(elements: Iterable[qf.Operation] = None)

A quantum Circuit contains a sequences of circuit elements. These can be any quantum Operation, including other circuits.

QuantumFlow’s circuit can only contain Operations. They do not contain control flow of other classical computations(similar to pyquil’s protoquil). For hybrid algorithms involving control flow and other classical processing use QuantumFlow’s Program class.


Returns the Hermitian conjugate of this circuit. If all the subsidiary gates are unitary, returns the circuit inverse.

add(other: qf.Circuit) → qf.Circuit

Concatenate gates and return new circuit

aschannel() → qf.Channel

Convert this quantum operation to a channel (if possible)

asgate() → qf.Gate

Return the action of this circuit as a gate

evolve(rho: qf.Density = None) → qf.Density

Apply the action of this operation upon a mixed state

extend(other: qf.Operation) → None

Append gates from circuit to the end of this circuit


Returns – Sorted list of qubits acted upon by this circuit

Raises:TypeError – If qubits cannot be sorted into unique order.
run(ket: qf.State = None) → qf.State

Apply the action of this circuit upon a state.

If no initial state provided an initial zero state will be created.

size() → int

Return the number of operations in this circuit

class quantumflow.DAGCircuit(elements: Iterable[qf.Operation])

A Directed Acyclic Graph representation of a Circuit.

The circuit is converted to a networkx directed acyclic multi-graph, stored in the graph attribute.

There are 3 node types, ‘in’ nodes representing qubits at the start of a circuit; operation nodes; and ‘out’ nodes for qubits at the end of a circuit. Edges are directed from ‘in’ to ‘out’ via the Operation nodes. Each edge is keyed to a qubit.

A DAGCircuit is considered a mutable object, like Circuit, the other composite Operation class.

DAGCircuit is iterable, yielding all of the operation nodes in topological sort order.

Note: Provisional API


Return the Hermitian conjugate of this quantum operation.

For unitary Gates (and Circuits composed of the same) the Hermitian conjugate returns the inverse Gate (or Circuit)

aschannel() → qf.Channel

Convert this quantum operation to a channel (if possible)

asgate() → qf.Gate

Convert this quantum operation to a gate (if possible)

component_nb() → int

Return the number of independent components that this DAGCircuit can be split into.

components() → List[quantumflow.dagcircuit.DAGCircuit]

Split DAGCircuit into independent components

depth(local: bool = True) → int

Return the circuit depth.

Parameters:local – If True include local one-qubit gates in depth calculation. Else return the multi-qubit gate depth.
evolve(rho: qf.Density) → qf.Density

Apply the action of this operation upon a mixed state

layers() → qf.Circuit

Split DAGCircuit into layers, where the operations within each layer operate on different qubits (and therefore commute).

Returns: A Circuit of Circuits, one Circuit per layer


Return the total number of qubits


Return the qubits that this operation acts upon

run(ket: qf.State) → qf.State

Apply the action of this operation upon a pure state

size() → int

Return the number of operations.

Standard circuits

quantumflow.qft_circuit(qubits: Qubits) → qf.Circuit

Returns the Quantum Fourier Transform circuit

quantumflow.reversal_circuit(qubits: Qubits) → qf.Circuit

Returns a circuit to reverse qubits

quantumflow.control_circuit(controls: Qubits, gate: qf.Gate) → qf.Circuit

Returns a circuit for a target gate controlled by a collection of control qubits. [Barenco1995]

Uses a number of gates quadratic in the number of control qubits.

[Barenco1995]A. Barenco, C. Bennett, R. Cleve (1995) Elementary Gates for Quantum Computation`<>`_ Sec 7.2
quantumflow.ccnot_circuit(qubits: Qubits) → qf.Circuit

Standard decomposition of CCNOT (Toffoli) gate into six CNOT gates (Plus Hadamard and T gates.) [Nielsen2000]

[Nielsen2000]M. A. Nielsen and I. L. Chuang, Quantum Computation and Quantum Information, Cambridge University Press (2000).
quantumflow.zyz_circuit(t0: float, t1: float, t2: float, q0: Qubit) → qf.Circuit

Circuit equivalent of 1-qubit ZYZ gate

quantumflow.phase_estimation_circuit(gate: qf.Gate, outputs: Qubits) → qf.Circuit

Returns a circuit for quantum phase estimation.

The gate has an eigenvector with eigenvalue e^(i 2 pi phase). To run the circuit, the eigenvector should be set on the gate qubits, and the output qubits should be in the zero state. After evolution and measurement, the output qubits will be (approximately) a binary fraction representation of the phase.

The output registers can be converted with the aid of the quantumflow.utils.bitlist_to_int() method.

>>> import numpy as np
>>> import quantumflow as qf
>>> N = 8
>>> phase = 1/4
>>> gate = qf.RZ(-4*np.pi*phase, N)
>>> circ = qf.phase_estimation_circuit(gate, range(N))
>>> res =[0:N]
>>> est_phase = int(''.join([str(d) for d in res]), 2) / 2**N # To float
>>> print(phase, est_phase)
0.25 0.25
quantumflow.addition_circuit(addend0: Qubits, addend1: Qubits, carry: Qubits) → qf.Circuit

Returns a quantum circuit for ripple-carry addition. [Cuccaro2004]

Requires two carry qubit (input and output). The result is returned in addend1.

[Cuccaro2004]A new quantum ripple-carry addition circuit, Steven A. Cuccaro, Thomas G. Draper, Samuel A. Kutin, David Petrie Moulton arXiv:quant-ph/0410184 (2004)
quantumflow.ghz_circuit(qubits: Qubits) → qf.Circuit

Returns a circuit that prepares a multi-qubit Bell state from the zero state.

Gate decompositions

quantumflow.bloch_decomposition(gate: qf.Gate) → qf.Circuit

Converts a 1-qubit gate into a RN gate, a 1-qubit rotation of angle theta about axis (nx, ny, nz) in the Bloch sphere.

Returns:A Circuit containing a single RN gate
quantumflow.zyz_decomposition(gate: qf.Gate) → qf.Circuit

Returns the Euler Z-Y-Z decomposition of a local 1-qubit gate.

quantumflow.kronecker_decomposition(gate: qf.Gate) → qf.Circuit

Decompose a 2-qubit unitary composed of two 1-qubit local gates.

Uses the “Nearest Kronecker Product” algorithm. Will give erratic results if the gate is not the direct product of two 1-qubit gates.

quantumflow.canonical_decomposition(gate: qf.Gate) → qf.Circuit

Decompose a 2-qubit gate by removing local 1-qubit gates to leave the non-local canonical two-qubit gate. [1] [2] [3] [4]

Returns: A Circuit of 5 gates: two initial 1-qubit gates; a CANONICAL gate, with coordinates in the Weyl chamber; two final 1-qubit gates

The canonical coordinates can be found in circ.elements[2].params

More or less follows the algorithm outlined in [2].

[1]A geometric theory of non-local two-qubit operations, J. Zhang, J. Vala, K. B. Whaley, S. Sastry quant-ph/0291120
[2](1, 2) An analytical decomposition protocol for optimal implementation of two-qubit entangling gates. M. Blaauboer, R.L. de Visser, cond-mat/0609750
[3]Metric structure of two-qubit gates, perfect entangles and quantum control, P. Watts, M. O’Conner, J. Vala, Entropy (2013)
[4]Constructive Quantum Shannon Decomposition from Cartan Involutions B. Drury, P. Love, arXiv:0806.4015
quantumflow.canonical_coords(gate: qf.Gate) → Sequence[float]

Returns the canonical coordinates of a 2-qubit gate


quantumflow.circuit_to_latex(circ: qf.Circuit, qubits: Qubits = None, document: bool = True) → str

Create an image of a quantum circuit in LaTeX.

Can currently draw X, Y, Z, H, T, S, T_H, S_H, RX, RY, RZ, TX, TY, TZ, CNOT, CZ, SWAP, ISWAP, CCNOT, CSWAP, XX, YY, ZZ, P0 and P1 gates, and the RESET operation.

  • circ – A quantum Circuit
  • qubits – Optional qubit list to specify qubit order
  • document – If false, just the qcircuit latex is returned. Else the circuit image is wrapped in a standalone LaTeX document ready for typesetting.

A LaTeX string representation of the circuit.


NotImplementedError – For unsupported gates.

LaTeX Qcircuit package
quantumflow.render_latex(latex: str) → <module 'PIL.Image' from '/home/docs/checkouts/'>

Convert a single page LaTeX document into an image.

To display the returned image,

Required external dependencies: pdflatex (with qcircuit package), and poppler (for pdftocairo).

Parameters:LaTeX document as a string. (A) –
Returns:A PIL Image
Raises:OSError – If an external dependency is not installed.