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: Optional[int] = None, num_bits: Optional[int] = None)

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: Optional[dwave.gate.primitives.Bit] = None, creg_label: Optional[Hashable] = None) → None

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: Optional[Hashable] = None) → None

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: Optional[Hashable] = None) → None

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: Optional[dwave.gate.primitives.Qubit] = None, qreg_label: Optional[Hashable] = None) → None

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

Appends an operation to the circuit.

Parameters

operation – Operation to append to the circuit.

bits

Classical bits handled by the circuit.

property circuit: List[Operation]

Circuit containing the applied operations.

property context: dwave.gate.circuit.CircuitContext

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, dwave.gate.registers.registers.ClassicalRegister]

Classical registers of the circuit.

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

property density_matrix: Optional[NDArray]

The density matrix representation of the state.

extend(operations: Sequence[Operation]) → None

Appends a sequence of operations to the circuit.

Parameters

operations – Operations to append to the circuit.

find_bit(bit: dwave.gate.primitives.Bit, creg_label: bool = False) → Tuple[Hashable, int]

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: dwave.gate.primitives.Qubit, qreg_label: bool = False) → Tuple[Hashable, int]

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.

get_bit(label: str, creg_label: Optional[str] = None, return_all: bool = False) → Union[dwave.gate.primitives.Bit, Sequence[dwave.gate.primitives.Bit]]

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: Optional[str] = None, return_all: bool = False) → Union[dwave.gate.primitives.Qubit, Sequence[dwave.gate.primitives.Qubit]]

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

Whether the circuit is locked or not.

lock() → None

Locks the circuit so that no more operations can be applied.

property num_bits: int

Number of bits in the circuit.

property num_parameters: int

Number of parameters in the circuit.

property num_qubits: int

Number of qubits in the circuit.

property parametric: bool

Whether the circuit has parameter variables.

property qregisters: Mapping[Hashable, dwave.gate.registers.registers.QuantumRegister]

Quantum registers of the circuit.

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

qubits

Qubits handled by the circuit.

remove(op: Operation) → None

Removes the operation from the circuit.

Parameters

op – Operation to remove.

reset(keep_registers: bool = True) → None

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

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: Optional[NDArray]

The resulting state after simulating the circuit.

to_qasm(version: str = '2.0', **kwargs) → str

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

unlock() → None

Unlocks the circuit allowing for further operations to be applied.

class CircuitContext(circuit: dwave.gate.circuit.Circuit)

Bases: object

Class used to handle and store the active context.

Parameters

circuit – Circuit to which the context is attached

active_context = None

property circuit: dwave.gate.circuit.Circuit

Circuit attached to the context.

freeze = <dwave.gate.circuit.CircuitContext.freeze.<locals>.FrozenContext object>

property frozen: bool

Whether the context is frozen and no operations can be appended.

on_exit_functions: List[Callable] = []

List of functions that should be called on context exit. Cleared on context exit.

exception CircuitError

Bases: Exception

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

class ParametricCircuit(num_qubits: Optional[int] = None, num_bits: Optional[int] = None)

Bases: dwave.gate.circuit.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: dwave.gate.circuit.ParametricCircuitContext

Circuit context used to apply operations to the circuit.

eval(parameters: Optional[Sequence[Sequence[complex]]] = None, in_place: bool = False) → dwave.gate.circuit.ParametricCircuit

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).

• in_place – 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

Number of parameters in the circuit.

property parametric: bool

Whether the circuit has parameter variables.

reset_variables() → None

Resets any variables in the parameter register by setting their values to None.

to_qasm() → str

Converts the Circuit into an OpenQASM string.

Note, not supported for parametric circuits.

unlock() → None

Unlocks the circuit allowing for further operations to be applied.

class ParametricCircuitContext(circuit: dwave.gate.circuit.ParametricCircuit)

Bases: dwave.gate.circuit.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)

Bases: object

Classical bit type.

Parameters

label – Label used to represent the bit.

property id: str

The bit’s unique identification number.

property label: Hashable

The bit’s label.

reset() → None

Reset the bit value to None.

set(value: int, force: bool = False) → None

Set a value for the bit.

Parameters

• value – Value that the variable should have.

• force – Whether to replace any previously set value.

property value: Optional[int]

The bit value, if set.

class Qubit(label: Hashable)

Bases: object

Qubit type.

Parameters

label – Label used to represent the qubit.

property id: str

The qubit’s unique identification number.

property label: Hashable

The qubit’s name.

class Variable(name: str)

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

The variable name.

reset()

Reset the variable value to None.

set(value: complex)

Set a value for the variable.

Parameters

value – Value that the variable should have.

property value: Optional[complex]

The variable value, if set.