pytket.circuit.Circuit¶

Circuit objects provide an abstraction of quantum circuits. They consist of a set of qubits/quantum wires and a collection of operations applied to them in a given order. These wires have open inputs and outputs, rather than assuming any fixed input state.

See the pytket User Manual for a step-by-step tutorial on constructing circuits.

See also the notebook tutorials on circuit generation and circuit analysis.

Many of the Circuit methods described below append a gate or box to the end of the circuit. Where kwargs are indicated in these methods, the following keyword arguments are supported:

opgroup (str): name of the associated operation group, if any
condition (Bit, BitLogicExp or Predicate): classical condition for applying operation
condition_bits (list of Bit): classical bits on which to condition operation
condition_value (int): required value of condition bits (little-endian), defaulting to all-1s if not specified

(Thus there are two ways to express classical conditions: either using a general condition, or using the pair condition_bits and condition_value to condition on a specified set of bit values.)

class pytket.circuit.Circuit¶

Encapsulates a quantum circuit using a DAG representation.

>>> from pytket import Circuit
>>> c = Circuit(4,2) # Create a circuit with 4 qubits and 2 classical bits
>>> c.H(0) # Apply a gate to qubit 0
>>> c.Rx(0.5,1) # Angles of rotation are expressed in half-turns (i.e. 0.5 means PI/2)
>>> c.Measure(1,0) # Measure qubit 1, saving result in bit 0

__init__(*args, **kwargs)¶

Overloaded function.

__init__(self: pytket._tket.circuit.Circuit) -> None

Constructs a circuit with a completely empty DAG.

__init__(self: pytket._tket.circuit.Circuit, name: str) -> None

Constructs a named circuit with a completely empty DAG.

Parameters:: name – name for the circuit

__init__(self: pytket._tket.circuit.Circuit, n_qubits: int, name: Optional[str] = None) -> None

Constructs a circuit with a given number of qubits/blank wires.

>>> c = Circuit()
>>> c.add_blank_wires(3)

is equivalent to

>>> c = Circuit(3)

Parameters:

n_qubits – The number of qubits in the circuit
name – Optional name for the circuit.

__init__(self: pytket._tket.circuit.Circuit, n_qubits: int, n_bits: int, name: Optional[str] = None) -> None

Constructs a circuit with a given number of quantum and classical bits

Parameters:

n_qubits – The number of qubits in the circuit
n_bits – The number of classical bits in the circuit
name – Optional name for the circuit.

__iter__(self: pytket._tket.circuit.Circuit) → Iterator[pytket._tket.circuit.Command]¶: Iterate through the circuit, a Command at a time.

__rshift__(self: pytket._tket.circuit.Circuit, arg0: pytket._tket.circuit.Circuit) → pytket._tket.circuit.Circuit¶: Creates a new Circuit, corresponding to the sequential composition of the given Circuits. Any qubits/bits with the same ids will be unified. Any ids without a match will be added in parallel.

add_gate(*args, **kwargs)¶

Overloaded function.

add_gate(self: pytket._tket.circuit.Circuit, Op: pytket._tket.circuit.Op, args: Sequence[int], **kwargs) -> pytket._tket.circuit.Circuit

Appends a single operation to the end of the circuit on some particular qubits/bits. The number of qubits/bits specified must match the arity of the gate.

add_gate(self: pytket._tket.circuit.Circuit, Op: pytket._tket.circuit.Op, args: Sequence[pytket._tket.unit_id.UnitID], **kwargs) -> pytket._tket.circuit.Circuit

Appends a single operation to the end of the circuit on some particular qubits/bits. The number of qubits/bits specified must match the arity of the gate.

add_gate(self: pytket._tket.circuit.Circuit, type: pytket._tket.circuit.OpType, args: Sequence[int], **kwargs) -> pytket._tket.circuit.Circuit

Appends a single (non-parameterised) gate to the end of the circuit on some particular qubits from the default register (‘q’). The number of qubits specified must match the arity of the gate. For OpType.Measure operations the bit from the default register should follow the qubit.

>>> c.add_gate(OpType.H, [0]) # equivalent to c.H(0)
>>> c.add_gate(OpType.CX, [0,1]) # equivalent to c.CX(0,1)

Parameters:

type – The type of operation to add
args – The list of indices for the qubits/bits to which the operation is applied
kwargs – Additional properties for classical conditions

Returns:

the new Circuit

add_gate(self: pytket._tket.circuit.Circuit, type: pytket._tket.circuit.OpType, args: Sequence[pytket._tket.unit_id.UnitID], **kwargs) -> pytket._tket.circuit.Circuit

>>> c.add_gate(OpType.H, [0]) # equivalent to c.H(0)
>>> c.add_gate(OpType.CX, [0,1]) # equivalent to c.CX(0,1)

Parameters:

type – The type of operation to add
args – The qubits/bits to apply the gate to
kwargs – Additional properties for classical conditions

Returns:

the new Circuit

add_gate(self: pytket._tket.circuit.Circuit, type: pytket._tket.circuit.OpType, angle: typing.Union[sympy.Expr, float], args: Sequence[int], **kwargs) -> pytket._tket.circuit.Circuit

Appends a single gate, parameterised by an expression, to the end of circuit on some particular qubits from the default register (‘q’).

Parameters:

type – The type of gate to add
angle – The parameter for the gate in halfturns
args – The list of indices for the qubits to which the operation is applied
kwargs – Additional properties for classical conditions

Returns:

the new Circuit

add_gate(self: pytket._tket.circuit.Circuit, type: pytket._tket.circuit.OpType, angle: typing.Union[sympy.Expr, float], args: Sequence[pytket._tket.unit_id.UnitID], **kwargs) -> pytket._tket.circuit.Circuit

Appends a single gate, parameterised by an expression, to the end of circuit on some particular qubits from the default register (‘q’).

Parameters:

type – The type of gate to add
angle – The parameter for the gate in halfturns
args – The qubits/bits to apply the gate to
kwargs – Additional properties for classical conditions

Returns:

the new Circuit

add_gate(self: pytket._tket.circuit.Circuit, type: pytket._tket.circuit.OpType, angles: Sequence[typing.Union[sympy.Expr, float]], args: Sequence[int], **kwargs) -> pytket._tket.circuit.Circuit

Appends a single gate, parameterised with a vector of expressions corresponding to halfturns, to the end of circuit on some particular qubits from the default register (‘q’).

Parameters:

type – The type of gate to add
angles – The parameters for the gate in halfturns
args – The list of indices for the qubits to which the operation is applied
kwargs – Additional properties for classical conditions

Returns:

the new Circuit

add_gate(self: pytket._tket.circuit.Circuit, type: pytket._tket.circuit.OpType, angles: Sequence[typing.Union[sympy.Expr, float]], args: Sequence[pytket._tket.unit_id.UnitID], **kwargs) -> pytket._tket.circuit.Circuit

Appends a single gate to the end of the circuit

Parameters:

type – The type of gate to add
params – The parameters for the gate in halfturns
args – The qubits/bits to apply the gate to
kwargs – Additional properties for classical conditions

Returns:

the new Circuit

append(self: pytket._tket.circuit.Circuit, circuit: pytket._tket.circuit.Circuit) → None¶

In-place sequential composition of circuits, appending a copy of the argument onto the end of the circuit. Inputs and Outputs are unified if they share the same id, defaulting to parallel composition if there is no match.

Parameters:: circuit – The circuit to be appended to the end of self

add_circuit(*args, **kwargs)¶

Overloaded function.

add_circuit(self: pytket._tket.circuit.Circuit, circuit: pytket._tket.circuit.Circuit, qubits: Sequence[pytket._tket.unit_id.Qubit], bits: Sequence[pytket._tket.unit_id.Bit] = []) -> pytket._tket.circuit.Circuit

In-place sequential composition of circuits, appending a copy of the argument onto the end of the circuit. Connects qubits and bits with the same behaviour as add_gate().

Parameters:

circuit – The circuit to be appended to the end of self
qubits – List mapping the (default register) qubits of circuit to the qubits of self
bits – List mapping the (default register) bits of circuit to the bits of self

Returns:

the new Circuit

add_circuit(self: pytket._tket.circuit.Circuit, circuit: pytket._tket.circuit.Circuit, qubits: Sequence[int], bits: Sequence[int] = []) -> pytket._tket.circuit.Circuit

In-place sequential composition of circuits, appending a copy of the argument onto the end of the circuit. Connects qubits and bits with the same behaviour as add_gate().

Parameters:

circuit – The circuit to be appended to the end of self
qubits – List mapping the (default register) qubits of circuit to the (default register) qubits of self
bits – List mapping the (default register) bits of circuit to the (default register) bits of self

Returns:

the new Circuit

add_qubit(self: pytket._tket.circuit.Circuit, id: pytket._tket.unit_id.Qubit, reject_dups: bool = True) → None¶

Constructs a single qubit with the given id.

Parameters:

id – Unique id for the qubit
reject_dups – Fail if there is already a qubit in this circuit with the id. Default to True

add_bit(self: pytket._tket.circuit.Circuit, id: pytket._tket.unit_id.Bit, reject_dups: bool = True) → None¶

Constructs a single bit with the given id.

Parameters:

id – Unique id for the bit
reject_dups – Fail if there is already a bit in this circuit with the id. Default to True

add_phase(self: pytket._tket.circuit.Circuit, a: Union[sympy.Expr, float]) → pytket._tket.circuit.Circuit¶

Add a global phase to the circuit.

Parameters:: a – Phase to add, in halfturns
Returns:: circuit with added phase

property name¶

property n_qubits¶

the number of qubits in the circuit

Type:: return

property n_bits¶

the number of classiclal bits in the circuit

Type:: return

property phase¶

the global phase applied to the circuit, in halfturns (not meaningful for circuits with classical interactions)

Type:: return

property qubits¶: A list of all qubit ids in the circuit

property bits¶: A list of all classical bit ids in the circuit

property n_gates¶

the number of gates in the Circuit

Type:: return

add_q_register(*args, **kwargs)¶

Overloaded function.

add_q_register(self: pytket._tket.circuit.Circuit, name: str, size: int) -> pytket._tket.unit_id.QubitRegister

Constructs a new quantum register with a given name and number of qubits.

Parameters:

name – Unique readable name for the register
size – Number of qubits required

Returns:

a map from index to the corresponding UnitIDs

add_q_register(self: pytket._tket.circuit.Circuit, register: pytket._tket.unit_id.QubitRegister) -> pytket._tket.unit_id.QubitRegister

Adds QubitRegister to Circuit

Parameters:: register – QubitRegister

get_q_register(self: pytket._tket.circuit.Circuit, name: str) → pytket._tket.unit_id.QubitRegister¶

Get the quantum register with the given name.

Parameters:: name – name for the register
Returns:: the retrieved QubitRegister

add_c_register(*args, **kwargs)¶

Overloaded function.

add_c_register(self: pytket._tket.circuit.Circuit, name: str, size: int) -> pytket._tket.unit_id.BitRegister

Constructs a new classical register with a given name and number of bits.

Parameters:

name – Unique readable name for the register
size – Number of bits required

Returns:

a map from index to the corresponding UnitIDs

add_c_register(self: pytket._tket.circuit.Circuit, register: pytket._tket.unit_id.BitRegister) -> pytket._tket.unit_id.BitRegister

Adds BitRegister to Circuit

Parameters:: register – BitRegister

get_c_register(self: pytket._tket.circuit.Circuit, name: str) → pytket._tket.unit_id.BitRegister¶

Get the classical register with the given name.

Parameters:: name – name for the register
Returns:: the retrieved BitRegister

property q_registers¶

Get all quantum registers.

The list only includes registers that are singly-indexed contiguously from zero.

Returns:: List of QubitRegister

property c_registers¶

Get all classical registers.

The list only includes registers that are singly-indexed contiguously from zero.

Returns:: List of BitRegister

rename_units(self: pytket._tket.circuit.Circuit, map: dict[pytket._tket.unit_id.UnitID | pytket._tket.unit_id.Qubit | pytket._tket.unit_id.Bit, pytket._tket.unit_id.UnitID | pytket._tket.unit_id.Qubit | pytket._tket.unit_id.Bit]) → bool¶

Rename qubits and bits simultaneously according to the map of ids provided

Parameters:: map – Dictionary from current ids to new ids

add_blank_wires(self: pytket._tket.circuit.Circuit, number: int) → None¶

Adds a number of new qubits to the circuit. These will be added to the default register (‘q’) if possible, filling out the unused indices from 0.

Parameters:: number – Number of qubits to add

remove_blank_wires(self: pytket._tket.circuit.Circuit, keep_blank_classical_wires: bool = False) → None¶

Removes any Input-Output pairs in the DAG with no intervening operations, i.e. removes untouched qubits/bits from the circuit. This may occur when optimisations recognise that the operations on a qubit reduce to the identity, or when routing adds wires to “fill out” the architecture. This operation will only remove empty classical wires if there are no used bits with a higher index in the same register.

Parameters:: keep_blank_classical_wires – select if empty classical wires should not be removed

flatten_registers(self: pytket._tket.circuit.Circuit, relabel_classical_expression: bool = True) → dict[pytket._tket.unit_id.UnitID, pytket._tket.unit_id.UnitID]¶

Combines all qubits into a single register namespace with the default name, and likewise for bits

Parameters:: relabel_classical_expression – Determines whether python classical expressions held in ClassicalExpBox have their expression relabelled to match relabelled Bit.

property qubit_readout¶: A map from qubit to its (left-to-right) index in readouts from backends. A qubit will feature in this map if it is measured and neither it nor the bit containing the measurement result is subsequently acted on

property bit_readout¶: A map from bit to its (left-to-right) index in readouts from backends (following the increasing lexicographic order convention)

property opgroups¶: A set of all opgroup names in the circuit

property is_simple¶: Checks that the circuit has only 1 quantum and 1 classic register using the default names (‘q’ and ‘c’). This means it is suitable to refer to qubits simply by their integer indices.

property qubit_to_bit_map¶: A map from qubit to the bit it is measured to. A qubit will feature in this map if it is measured and neither it nor the bit containing the measurement result is subsequently acted on

commands_of_type(self: pytket._tket.circuit.Circuit, optype: pytket._tket.circuit.OpType) → list[pytket._tket.circuit.Command]¶

Get all commands in a circuit of a given type.

The order is consistent with the causal order of the operations in the circuit.

Parameters:: optype – operation type
Returns:: list of Command

ops_of_type(self: pytket._tket.circuit.Circuit, optype: pytket._tket.circuit.OpType) → list[pytket._tket.circuit.Op]¶

Get all operations in the circuit of a given type.

The order is not guaranteed.

Parameters:: optype – operation type
Returns:: list of Op

n_gates_of_type(self: pytket._tket.circuit.Circuit, type: pytket._tket.circuit.OpType, include_conditional: bool = False) → int¶

Returns the number of vertices in the dag of a given operation type.

>>> c.CX(0,1)
>>> c.H(0)
>>> c.CX(0,1)
>>> c.n_gates_of_type(OpType.CX)
2

Parameters:

type – The operation type to search for
include_conditional – if set to true, conditional gates will be counted, too

Returns:

the number of operations matching type

n_1qb_gates(self: pytket._tket.circuit.Circuit) → int¶: Returns the number of vertices in the dag with one quantum edge.Ignores Input, Create, Output, Discard, Reset, Measure and Barrier vertices.

n_2qb_gates(self: pytket._tket.circuit.Circuit) → int¶: Returns the number of vertices in the dag with two quantum edges.Ignores Input, Create, Output, Discard, Reset, Measure and Barrier vertices.

n_nqb_gates(self: pytket._tket.circuit.Circuit, size: int) → int¶: Returns the number of vertices in the dag with given number of quantum edges.Ignores Input, Create, Output, Discard, Reset, Measure and Barrier vertices.

free_symbols(self: pytket._tket.circuit.Circuit) → set[sympy.Symbol]¶

Returns:: set of symbolic parameters in the circuit

symbol_substitution(*args, **kwargs)¶

Overloaded function.

symbol_substitution(self: pytket._tket.circuit.Circuit, symbol_map: dict[sympy.Symbol, typing.Union[sympy.Expr, float]]) -> None

In-place substitution for symbolic expressions; iterates through each parameterised gate/box and performs the substitution.

Parameters:: symbol_map – A map from SymPy symbols to SymPy expressions

symbol_substitution(self: pytket._tket.circuit.Circuit, symbol_map: dict[sympy.Symbol, float]) -> None

In-place substitution for symbolic expressions; iterates through each gate/box and performs the substitution.

Parameters:: symbol_map – A map from SymPy symbols to floating-point values

substitute_named(*args, **kwargs)¶

Overloaded function.

substitute_named(self: pytket._tket.circuit.Circuit, op: pytket._tket.circuit.Op, opgroup: str) -> bool

Substitute all ops with the given name for the given op.The replacement operations retain the same name.

Parameters:

op – the replacement operation
opgroup – the name of the operations group to replace

Returns: