Circuits#

Circuit Module#

Circuit and context manager classes.

Contains classes to construct and handle quantum circuits. The quantum circuits contain the quantum operations and instructions for running the circuits on simulators or hardware. See dwave.gate.operations for details on which operations are supported.

class Circuit(num_qubits: int | None = None, num_bits: int | None = None)[source]#

Bases: object

Class to build and manipulate quantum circuits.

Parameters:

num_qubits – Number of qubits in the circuit.
num_bits – Number of classical bits in the circuit.

add_bit(bit: Bit | None = None, creg_label: Hashable | None = None) → None[source]#

Add a single bit to a classical register.

Parameters:

bit – Bit to add to the circuit. If None, then a new bit is created.
creg_label – Label for the classical register to which the new bit should be appended (defaults to ‘r’ followed by a random integer ID number).

add_cregister(num_bits: int = 0, label: Hashable | None = None) → None[source]#

Adds a new classical register to the circuit.

Parameters:

num_qubits – Number of bits in the classical register (defaults to 0, i.e., empty).
label – Classical register label (defaults to ‘creg’ followed by a incrementing integer starting at 0).

add_qregister(num_qubits: int = 0, label: Hashable | None = None) → None[source]#

Adds a new quantum register to the circuit.

Parameters:

num_qubits – Number of qubits in the quantum register (defaults to 0, i.e., empty).
label – Quantum register label (defaults to ‘qreg’ followed by a incrementing integer starting at 0).

add_qubit(qubit: Qubit | None = None, qreg_label: Hashable | None = None) → None[source]#

Add a single qubit to a quantum register in the circuit.

Parameters:

qubit – Qubit to add to the circuit. If None, then a new qubit is created.
qreg_label – Label for the quantum register to which the new qubit should be appended (defaults to ‘r’ followed by a random integer ID number).

append(operation: Operation) → None[source]#

Appends an operation to the circuit.

Parameters:: operation – Operation to append to the circuit.

property bits: ClassicalRegister[source]#: Classical bits handled by the circuit.

property circuit: list[Operation][source]#: Circuit containing the applied operations.

property context: CircuitContext[source]#

Circuit context used to apply operations to the circuit.

A dwave.gate.circuit.Registers is returned when entering the context, which contains the quantum and classical registers, named q and c respectively. These contain all qubits and classical bits respectively and can be used to reference operation applications and measurement values. All operations initialized within the context are automatically applied to the circuit unless called within a frozen context.

property cregisters: Mapping[Hashable, ClassicalRegister][source]#

Classical registers of the circuit.

Returns a dictionary with classical register labels as keys and ClassicalRegister objects as values.

property density_matrix: NDArray | None[source]#: The density matrix representation of the state.

extend(operations: Sequence[Operation]) → None[source]#

Appends a sequence of operations to the circuit.

Parameters:: operations – Operations to append to the circuit.

find_bit(bit: Bit, creg_label: bool = False) → tuple[Hashable, int][source]#

Returns the register where a bit contained and its index in the register.

Parameters:

bit – The bit to find.
creg_label – Whether to return the containing classical register label (True) or its index (False) in the self.cregisters dictionary.

Returns:

Tuple containing the classical register label and the index of the bit in that register.

Return type:

tuple

Raises:

ValueError – If the bit is not found in any register.

find_qubit(qubit: Qubit, qreg_label: bool = False) → tuple[Hashable, int][source]#

Returns the register where a qubit contained and its index in the register.

Parameters:

qubit – The qubit to find.
qreg_label – Whether to return the containing quantum register label (True) or its index (False) in the self.qregisters dictionary.

Returns:

Tuple containing the quantum register label and the index of the qubit in that register.

Return type:

tuple

Raises:

ValueError – If the qubit is not found in any register.

classmethod from_qir(qir: str | bytes, bitcode: bool = False) → Circuit[source]#

Load a circuit from a QIR string or bitcode.

Parameters:

qir – The QIR string or bitcode to load into a circuit.
bitcode – Whether to expect the QIR as a string or as bitcode.

Returns:

The circuit represented by the QIR string or bitcode.

Return type:

Circuit

get_bit(label: str, creg_label: str | None = None, return_all: bool = False) → Bit | Sequence[Bit][source]#

Returns the Bit(s) with a specific label.

Parameters:

label – The label of the bit.
creg_label – Label of the classical register to search in. If None, all registers are searched.
return_all – Whether to return all bits if several exists with the same label, or just return the first occuring bit. Defaults to False.

Returns:

Bit with the specified label. If there are several with the same name, only the first occuring bit will be returned unless return_all is True.

Return type:

Bit

get_qubit(label: str, qreg_label: str | None = None, return_all: bool = False) → Qubit | Sequence[Qubit][source]#

Returns the Qubit(s) with a specific label.

Parameters:

label – The label of the qubit.
qreg_label – Label of the quantum register to search in. If None, all registers are searched.
return_all – Whether to return all qubits if several exists with the same label, or just return the first occuring qubit. Defaults to False.

Returns:

Qubit with the specified label. If there are several with the same name, only the first occuring qubit will be returned unless return_all is True.

Return type:

Qubit

is_locked() → bool[source]#: Whether the circuit is locked or not.

lock() → None[source]#: Locks the circuit so that no more operations can be applied.

property num_bits: int[source]#: Number of bits in the circuit.

property num_parameters: int[source]#: Number of parameters in the circuit.

property num_qubits: int[source]#: Number of qubits in the circuit.

property parametric: bool[source]#: Whether the circuit has parameter variables.

property qregisters: Mapping[Hashable, QuantumRegister][source]#

Quantum registers of the circuit.

Returns a dictionary with quantum register labels as keys and QuantumRegister objects as values.

property qubits: QuantumRegister[source]#: Qubits handled by the circuit.

remove(op: Operation) → None[source]#

Removes the operation from the circuit.

Parameters:: op – Operation to remove.

reset(keep_registers: bool = True) → None[source]#

Resets the circuit so that it can be reused.

Parameters:: keep_registers – If False, deletes the quantum and classical registers, removing all the current qubits in the circuit, including those created at initialization (defaults to True).

set_state(state: NDArray, force: bool = False, normalize: bool = False) → None[source]#

Set the state of the circuit (used primarily with simulator).

Sets either the Circuit.state attribute or the Circuit.density_matrix attribute depending on the shape of the state.

Parameters:

state – The state (pure or mixed) to set.
force – Whether to overwrite an already set state or not.
normalize – Whether to normalize the state before setting.

property state: NDArray | None[source]#: The resulting state after simulating the circuit.

to_qasm(version: str = '2.0', **kwargs) → str[source]#

Converts the Circuit into an OpenQASM string.

Parameters:

version – OpenQASM version (currently only supports 2.0).

Keyword Arguments:

reg_labels – Whether to use the qregister labels (True) given or to simplify them and simply use standard OpenQASM 2.0 labels, q0, q1, etc., instead (False). Defaults to False.
gate_definitions – Whether to add definitions for gates that are not part of the OpenQASM standard library file qelib1.inc. Defaults to False.

Returns:

OpenQASM string representation of the circuit.

Return type:

str

to_qir(add_external: bool = False, bitcode: bool = False) → str | bytes[source]#

Compile a circuit into QIR.

Parameters:

add_external – Whether to add external functions (not defined in QIR). If False, functions marked as external will be decomposed into valid operations (if possible).
bitcode – Whether to return QIR as a legible string or as bitcode.

Returns:

The QIR representation of the circuit.

Return type:

Union[str, bytes]

unlock() → None[source]#: Unlocks the circuit allowing for further operations to be applied.

class CircuitContext(circuit: Circuit)[source]#

Bases: object

Class used to handle and store the active context.

Parameters:: circuit – Circuit to which the context is attached

active_context = None[source]#

property circuit: Circuit[source]#: Circuit attached to the context.

freeze = <dwave.gate.circuit.CircuitContext.freeze.<locals>.FrozenContext object>[source]#

property frozen: bool[source]#: Whether the context is frozen and no operations can be appended.

on_exit_functions: list[Callable] = [][source]#: List of functions that should be called on context exit. Cleared on context exit.

exception CircuitError[source]#

Bases: Exception

Exception to be raised when there is an error with a Circuit.

class ParametricCircuit(num_qubits: int | None = None, num_bits: int | None = None)[source]#

Bases: Circuit

Class to build and manipulate parametric quantum circuits.

Parameters:

num_qubits – Number of qubits in the circuit.
num_bits – Number of classical bits in the circuit.

property context: ParametricCircuitContext[source]#: Circuit context used to apply operations to the circuit.

eval(parameters: Sequence[Sequence[complex]] | None = None, inplace: bool = False) → ParametricCircuit[source]#

Evaluate circuit operations with explicit parameters.

Parameters:

parameters – Parameters to replace operation variables with. Overrides potential variable values. If None then variable values are used (if existent).
inplace – Whether to evaluate the parameters on self or on a copy of self (returned).

Returns:

Either self or a copy of self.

Return type:

ParametricOperation

Raises:

ValueError – If no parameters are passed and if variable has no set value.

property num_parameters: int[source]#: Number of parameters in the circuit.

property parametric: bool[source]#: Whether the circuit has parameter variables.

reset_variables() → None[source]#: Resets any variables in the parameter register by setting their values to None.

to_qasm() → str[source]#

Converts the Circuit into an OpenQASM string.

Note, not supported for parametric circuits.

unlock() → None[source]#: Unlocks the circuit allowing for further operations to be applied.

class ParametricCircuitContext(circuit: ParametricCircuit)[source]#

Bases: CircuitContext

Class used to handle and store the active context with parametric circuits.

Parameters:: circuit – Parametric circuit to which the context is attached.

Primitives Module#

Primitive types used with quantum circuits.

Contains primitive types such as qubits, bits and variables.

class Bit(label: Hashable)[source]#

Bases: object

Classical bit type.

Parameters:: label – Label used to represent the bit.

property id: str[source]#: The bit’s unique identification number.

property label: Hashable[source]#: The bit’s label.

reset() → None[source]#: Reset the bit value to None.

set(value: int, force: bool = False) → None[source]#

Set a value for the bit.

Parameters:

value – Value that the variable should have.
force – Whether to replace any previously set value.

property value: int | None[source]#: The bit value, if set.

class Qubit(label: Hashable)[source]#

Bases: object

Qubit type.

Parameters:: label – Label used to represent the qubit.

property id: str[source]#: The qubit’s unique identification number.

property label: Hashable[source]#: The qubit’s name.

class Variable(name: str)[source]#

Bases: object

Variable parameter type.

Used as a placeholder for parameter values. Two variables with the same label are considered equal (Variable('a') == Variable('a')) and have the same hash value, but not identical (Variable('a') is not Variable('a'))

Parameters:: name – String used to represent the variable.

property name: str[source]#: The variable name.

reset()[source]#: Reset the variable value to None.

set(value: complex)[source]#

Set a value for the variable.

Parameters:: value – Value that the variable should have.

property value: complex | None[source]#: The variable value, if set.