Circuit

class braket.circuits.circuit.Circuit(addable=None, *args, **kwargs)

Bases: object

A representation of a quantum circuit that contains the instructions to be performed on a quantum device and the requested result types.

See braket.circuits.gates module for all of the supported instructions.

See braket.circuits.result_types module for all of the supported result types.

AddableTypes are Instruction, iterable of Instruction, ResultType, iterable of ResultType, or SubroutineCallable

Parameters:

addable (Optional[TypeVar(AddableTypes, TypeVar(SubroutineReturn, Iterable[Instruction], Instruction, ResultType, Iterable[ResultType]), TypeVar(SubroutineCallable, bound= Callable[..., TypeVar(SubroutineReturn, Iterable[Instruction], Instruction, ResultType, Iterable[ResultType])]))])

Inits a Circuit.

Parameters:

addable (AddableTypes | None) – The item(s) to add to self. Default = None.

Raises:

TypeError – If addable is an unsupported type.

Examples

>>> circ = Circuit([Instruction(Gate.H(), 4), Instruction(Gate.CNot(), [4, 5])])
>>> circ = Circuit().h(0).cnot(0, 1)
>>> circ = Circuit().h(0).cnot(0, 1).probability([0, 1])

>>> @circuit.subroutine(register=True)
>>> def bell_pair(target):
...     return Circ().h(target[0]).cnot(target[0:2])
>>> circ = Circuit(bell_pair, [4, 5])
>>> circ = Circuit().bell_pair([4, 5])

classmethod register_subroutine(func)

Register the subroutine func as an attribute of the Circuit class. The attribute name is the name of func.

Parameters:

func (SubroutineCallable) – The function of the subroutine to add to the class.

Return type:

None

Examples

>>> def h_on_all(target):
...     circ = Circuit()
...     for qubit in target:
...         circ += Instruction(Gate.H(), qubit)
...     return circ
>>> Circuit.register_subroutine(h_on_all)
>>> circ = Circuit().h_on_all(range(2))
>>> for instr in circ.instructions:
...     print(instr)
Instruction('operator': 'H', 'target': QubitSet(Qubit(0),))
Instruction('operator': 'H', 'target': QubitSet(Qubit(1),))

property depth: int

Get the circuit depth.

Type:

int

property global_phase: float

Get the global phase of the circuit.

Type:

float

property instructions: list[Instruction]

Get an iterable of instructions in the circuit.

Type:

Iterable[Instruction]

property result_types: list[ResultType]

Get a list of requested result types in the circuit.

Type:

list[ResultType]

property basis_rotation_instructions: list[Instruction]

Gets a list of basis rotation instructions.

Returns:

list[Instruction] – Get a list of basis rotation instructions in the circuit. These basis rotation instructions are added if result types are requested for an observable other than Pauli-Z.

This only makes sense if all observables are simultaneously measurable; if not, this method will return an empty list.

property moments: Moments

Get the moments for this circuit. Note that this includes observables.

Type:

Moments

property qubit_count: int

Get the qubit count for this circuit. Note that this includes observables.

Returns:

int – The qubit count for this circuit.

property qubits: QubitSet

Get a copy of the qubits for this circuit.

Type:

QubitSet

property parameters: set[FreeParameter]

Gets a set of the parameters in the Circuit.

Returns:

set[FreeParameter] – The FreeParameters in the Circuit.

with_euler_angles(observables)

Returns a copy of the circuit with parametrized Euler angles on the observables’ qubits

Parameters:

observables (Sequence[Observable] | Sum) – The observables to measure, or a Sum Hamiltonian

Return type:

Circuit

Returns:

Circuit – A new circuit with parametrized ZXZ Euler angle rotations appended to the end on each qubit targeted by any of the observables.

add_result_type(result_type, target=None, target_mapping=None)

Add a requested result type to self, returns self for chaining ability.

Parameters:

• result_type (ResultType) – ResultType to add into self.

• target (QubitSetInput | None) – Target qubits for the result_type. Default = None.

• target_mapping (dict[QubitInput, QubitInput] | None) – A dictionary of qubit mappings to apply to the result_type.target. Key is the qubit in result_type.target and the value is what the key will be changed to. Default = None.

Return type:

Circuit

Returns:

Circuit – self

Note

Target and target_mapping will only be applied to those requested result types with the attribute target. The result_type will be appended to the end of the dict keys of circuit.result_types only if it does not already exist in circuit.result_types

Raises:

• TypeError – If both target_mapping and target are supplied.

• ValueError – If a measure instruction exists on the current circuit.

Examples

>>> result_type = ResultType.Probability(target=[0, 1])
>>> circ = Circuit().add_result_type(result_type)
>>> print(circ.result_types[0])
Probability(target=QubitSet([Qubit(0), Qubit(1)]))

>>> result_type = ResultType.Probability(target=[0, 1])
>>> circ = Circuit().add_result_type(result_type, target_mapping={0: 10, 1: 11})
>>> print(circ.result_types[0])
Probability(target=QubitSet([Qubit(10), Qubit(11)]))

>>> result_type = ResultType.Probability(target=[0, 1])
>>> circ = Circuit().add_result_type(result_type, target=[10, 11])
>>> print(circ.result_types[0])
Probability(target=QubitSet([Qubit(10), Qubit(11)]))

>>> result_type = ResultType.StateVector()
>>> circ = Circuit().add_result_type(result_type)
>>> print(circ.result_types[0])
StateVector()

add_instruction(instruction, target=None, target_mapping=None)

Add an instruction to self, returns self for chaining ability.

Parameters:

• instruction (Instruction) – Instruction to add into self.

• target (QubitSetInput | None) – Target qubits for the instruction. If a single qubit gate, an instruction is created for every index in target. Default = None.

• target_mapping (dict[QubitInput, QubitInput] | None) – A dictionary of qubit mappings to apply to the instruction.target. Key is the qubit in instruction.target and the value is what the key will be changed to. Default = None.

Return type:

Circuit

Returns:

Circuit – self

Raises:

• TypeError – If both target_mapping and target are supplied.

• ValueError – If adding a gate or noise after a measure instruction.

Examples

>>> instr = Instruction(Gate.CNot(), [0, 1])
>>> circ = Circuit().add_instruction(instr)
>>> print(circ.instructions[0])
Instruction('operator': 'CNOT', 'target': QubitSet(Qubit(0), Qubit(1)))

>>> instr = Instruction(Gate.CNot(), [0, 1])
>>> circ = Circuit().add_instruction(instr, target_mapping={0: 10, 1: 11})
>>> print(circ.instructions[0])
Instruction('operator': 'CNOT', 'target': QubitSet(Qubit(10), Qubit(11)))

>>> instr = Instruction(Gate.CNot(), [0, 1])
>>> circ = Circuit().add_instruction(instr, target=[10, 11])
>>> print(circ.instructions[0])
Instruction('operator': 'CNOT', 'target': QubitSet(Qubit(10), Qubit(11)))

>>> instr = Instruction(Gate.H(), 0)
>>> circ = Circuit().add_instruction(instr, target=[10, 11])
>>> print(circ.instructions[0])
Instruction('operator': 'H', 'target': QubitSet(Qubit(10),))
>>> print(circ.instructions[1])
Instruction('operator': 'H', 'target': QubitSet(Qubit(11),))

add_circuit(circuit, target=None, target_mapping=None)

Add a Circuit to self, returning self for chaining ability.

Parameters:

• circuit (Circuit) – Circuit to add into self.

• target (QubitSetInput | None) – Target qubits for the supplied circuit. This is a macro over target_mapping; target is converted to a target_mapping by zipping together a sorted circuit.qubits and target. Default = None.

• target_mapping (dict[QubitInput, QubitInput] | None) – A dictionary of qubit mappings to apply to the qubits of circuit.instructions. Key is the qubit to map, and the value is what to change it to. Default = None.

Return type:

Circuit

Returns:

Circuit – self

Raises:

TypeError – If both target_mapping and target are supplied.

Note

Supplying target sorts circuit.qubits to have deterministic behavior since circuit.qubits ordering is based on how instructions are inserted. Use caution when using this with circuits that with a lot of qubits, as the sort can be resource-intensive. Use target_mapping to use a linear runtime to remap the qubits.

Requested result types of the circuit that will be added will be appended to the end of the list for the existing requested result types. A result type to be added that is equivalent to an existing requested result type will not be added.

Examples

>>> widget = Circuit().h(0).cnot(0, 1)
>>> circ = Circuit().add_circuit(widget)
>>> instructions = list(circ.instructions)
>>> print(instructions[0])
Instruction('operator': 'H', 'target': QubitSet(Qubit(0),))
>>> print(instructions[1])
Instruction('operator': 'CNOT', 'target': QubitSet(Qubit(0), Qubit(1)))

>>> widget = Circuit().h(0).cnot(0, 1)
>>> circ = Circuit().add_circuit(widget, target_mapping={0: 10, 1: 11})
>>> instructions = list(circ.instructions)
>>> print(instructions[0])
Instruction('operator': 'H', 'target': QubitSet(Qubit(10),))
>>> print(instructions[1])
Instruction('operator': 'CNOT', 'target': QubitSet(Qubit(10), Qubit(11)))

>>> widget = Circuit().h(0).cnot(0, 1)
>>> circ = Circuit().add_circuit(widget, target=[10, 11])
>>> instructions = list(circ.instructions)
>>> print(instructions[0])
Instruction('operator': 'H', 'target': QubitSet(Qubit(10),))
>>> print(instructions[1])
Instruction('operator': 'CNOT', 'target': QubitSet(Qubit(10), Qubit(11)))

add_verbatim_box(verbatim_circuit, target=None, target_mapping=None)

Add a verbatim Circuit to self, ensuring that the circuit is not modified in any way by the compiler.

Parameters:

• verbatim_circuit (Circuit) – Circuit to add into self.

• target (QubitSetInput | None) – Target qubits for the supplied circuit. This is a macro over target_mapping; target is converted to a target_mapping by zipping together a sorted circuit.qubits and target. Default = None.

• target_mapping (dict[QubitInput, QubitInput] | None) – A dictionary of qubit mappings to apply to the qubits of circuit.instructions. Key is the qubit to map, and the value is what to change it to. Default = None.

Return type:

Circuit

Returns:

Circuit – self

Raises:

• TypeError – If both target_mapping and target are supplied.

• ValueError – If circuit has result types attached

Examples

>>> widget = Circuit().h(0).h(1)
>>> circ = Circuit().add_verbatim_box(widget)
>>> print(list(circ.instructions))
[Instruction('operator': StartVerbatimBox, 'target': QubitSet([])),
 Instruction('operator': H('qubit_count': 1), 'target': QubitSet([Qubit(0)])),
 Instruction('operator': H('qubit_count': 1), 'target': QubitSet([Qubit(1)])),
 Instruction('operator': EndVerbatimBox, 'target': QubitSet([]))]

>>> widget = Circuit().h(0).cnot(0, 1)
>>> circ = Circuit().add_verbatim_box(widget, target_mapping={0: 10, 1: 11})
>>> print(list(circ.instructions))
[Instruction('operator': StartVerbatimBox, 'target': QubitSet([])),
 Instruction('operator': H('qubit_count': 1), 'target': QubitSet([Qubit(10)])),
 Instruction('operator': H('qubit_count': 1), 'target': QubitSet([Qubit(11)])),
 Instruction('operator': EndVerbatimBox, 'target': QubitSet([]))]

>>> widget = Circuit().h(0).cnot(0, 1)
>>> circ = Circuit().add_verbatim_box(widget, target=[10, 11])
>>> print(list(circ.instructions))
[Instruction('operator': StartVerbatimBox, 'target': QubitSet([])),
 Instruction('operator': H('qubit_count': 1), 'target': QubitSet([Qubit(10)])),
 Instruction('operator': H('qubit_count': 1), 'target': QubitSet([Qubit(11)])),
 Instruction('operator': EndVerbatimBox, 'target': QubitSet([]))]

barrier(target=None)

Add a barrier compiler directive to the circuit.

Parameters:

• target (QubitSetInput | None) – Target qubits for the barrier.

• None (If)

• circuit (applies to all qubits in the)

Return type:

Circuit

Returns:

Circuit – self

Raises:

ValueError – If target is None or empty and circuit has no qubits.

Examples

>>> circ = Circuit().h(0).barrier([0, 1]).cnot(0, 1)
>>> circ = Circuit().h(0).h(1).barrier()  # barrier on all qubits

measure(target_qubits)

Add a measure operator to self ensuring only the target qubits are measured.

Parameters:

target_qubits (QubitSetInput) – target qubits to measure.

Return type:

Circuit

Returns:

Circuit – self

Raises:

• IndexError – If self has no qubits.

• IndexError – If target qubits are not within the range of the current circuit.

• ValueError – If the current circuit contains any result types.

• ValueError – If the target qubit is already measured.

Examples

>>> circ = Circuit.h(0).cnot(0, 1).measure([0])
>>> circ.print(list(circ.instructions))
[Instruction('operator': H('qubit_count': 1), 'target': QubitSet([Qubit(0)]),
Instruction('operator': CNot('qubit_count': 2), 'target': QubitSet([Qubit(0),
    Qubit(1)]),
Instruction('operator': Measure, 'target': QubitSet([Qubit(0)])]

apply_gate_noise(noise, target_gates=None, target_unitary=None, target_qubits=None)

Apply noise to the circuit according to target_gates, target_unitary and target_qubits.

For any parameter that is None, that specification is ignored (e.g. if target_gates is None then the noise is applied after every gate in target_qubits). If target_gates and target_qubits are both None, then noise is applied to every qubit after every gate.

Noise is either applied to target_gates or target_unitary, so they cannot be provided at the same time.

When noise.qubit_count == 1, ie. noise is single-qubit, noise is added to all qubits in target_gates or target_unitary (or to all qubits in target_qubits if target_gates is None).

When noise.qubit_count > 1 and target_gates is not None, the number of qubits of any gate in target_gates must be the same as noise.qubit_count.

When noise.qubit_count > 1, target_gates and target_unitary is None, noise is only applied to gates with the same qubit_count in target_qubits.

Parameters:

• noise (type[Noise] | Iterable[type[Noise]]) – Noise channel(s) to be applied to the circuit.

• target_gates (type[Gate] | Iterable[type[Gate]] | None) – Gate class or List of Gate classes which noise is applied to. Default=None.

• target_unitary (np.ndarray | None) – matrix of the target unitary gates. Default=None.

• target_qubits (QubitSetInput | None) – Index or indices of qubit(s). Default=None.

Return type:

Circuit

Returns:

Circuit – self

Raises:

• TypeError – If noise is not Noise type. If target_gates is not a Gate type, Iterable[Gate]. If target_unitary is not a np.ndarray type. If target_qubits has non-integers or negative integers.

• IndexError – If applying noise to an empty circuit. If target_qubits is out of range of circuit.qubits.

• ValueError – If both target_gates and target_unitary are provided. If target_unitary is not a unitary. If noise is multi-qubit noise and target_gates contain gates with the number of qubits not the same as noise.qubit_count.

Warning

If noise is multi-qubit noise while there is no gate with the same number of qubits in target_qubits or in the whole circuit when target_qubits is not given. If no target_gates or target_unitary exist in target_qubits or in the whole circuit when they are not given.

Examples:

>>> circ = Circuit().x(0).y(1).z(0).x(1).cnot(0,1)
>>> print(circ)
T  : |0|1|2|

q0 : -X-Z-C-
          |
q1 : -Y-X-X-

T  : |0|1|2|

>>> noise = Noise.Depolarizing(probability=0.1)
>>> circ = Circuit().x(0).y(1).z(0).x(1).cnot(0,1)
>>> print(circ.apply_gate_noise(noise, target_gates = Gate.X))
T  : |     0     |     1     |2|

q0 : -X-DEPO(0.1)-Z-----------C-
                              |
q1 : -Y-----------X-DEPO(0.1)-X-

T  : |     0     |     1     |2|

>>> circ = Circuit().x(0).y(1).z(0).x(1).cnot(0,1)
>>> print(circ.apply_gate_noise(noise, target_qubits = 1))
T  : |     0     |     1     |     2     |

q0 : -X-----------Z-----------C-----------
                              |
q1 : -Y-DEPO(0.1)-X-DEPO(0.1)-X-DEPO(0.1)-

T  : |     0     |     1     |     2     |

>>> circ = Circuit().x(0).y(1).z(0).x(1).cnot(0,1)
>>> print(circ.apply_gate_noise(noise,
...                             target_gates = [Gate.X,Gate.Y],
...                             target_qubits = [0,1])
... )
T  : |     0     |     1     |2|

q0 : -X-DEPO(0.1)-Z-----------C-
                              |
q1 : -Y-DEPO(0.1)-X-DEPO(0.1)-X-

T  : |     0     |     1     |2|

apply_initialization_noise(noise, target_qubits=None)

Apply noise at the beginning of the circuit for every qubit (default) or target_qubits`.

Only when target_qubits is given can the noise be applied to an empty circuit.

When noise.qubit_count > 1, the number of qubits in target_qubits must be equal to noise.qubit_count.

Parameters:

• noise (type[Noise] | Iterable[type[Noise]]) – Noise channel(s) to be applied to the circuit.

• target_qubits (QubitSetInput | None) – Index or indices of qubit(s). Default=None.

Return type:

Circuit

Returns:

Circuit – self

Raises:

• TypeError – If noise is not Noise type. If target_qubits has non-integers or negative integers.

• IndexError – If applying noise to an empty circuit when target_qubits is not given.

• ValueError – If noise.qubit_count > 1 and the number of qubits in target_qubits is not the same as noise.qubit_count.

Examples

>>> circ = Circuit().x(0).y(1).z(0).x(1).cnot(0, 1)
>>> print(circ)

>>> noise = Noise.Depolarizing(probability=0.1)
>>> circ = Circuit().x(0).y(1).z(0).x(1).cnot(0, 1)
>>> print(circ.apply_initialization_noise(noise))

>>> circ = Circuit().x(0).y(1).z(0).x(1).cnot(0, 1)
>>> print(circ.apply_initialization_noise(noise, target_qubits=1))

>>> circ = Circuit()
>>> print(circ.apply_initialization_noise(noise, target_qubits=[0, 1]))

make_bound_circuit(param_values, strict=False)

Binds `FreeParameter`s based upon their name and values passed in. If parameters share the same name, all the parameters of that name will be set to the mapped value.

Parameters:

• param_values (dict[str, Number]) – A mapping of FreeParameter names to a value to assign to them.

• strict (bool) – If True, raises a ValueError if any of the FreeParameters in param_values do not appear in the circuit. False by default.

Return type:

Circuit

Returns:

Circuit – Returns a circuit with all present parameters fixed to their respective values.

apply_readout_noise(noise, target_qubits=None)

Apply noise right before measurement in every qubit (default) or target_qubits`.

Only when target_qubits is given can the noise be applied to an empty circuit.

When noise.qubit_count > 1, the number of qubits in target_qubits must be equal to noise.qubit_count.

Parameters:

• noise (type[Noise] | Iterable[type[Noise]]) – Noise channel(s) to be applied to the circuit.

• target_qubits (QubitSetInput | None) – Index or indices of qubit(s). Default=None.

Return type:

Circuit

Returns:

Circuit – self

Raises:

• TypeError – If noise is not Noise type. If target_qubits has non-integers.

• IndexError – If applying noise to an empty circuit.

• ValueError – If target_qubits has negative integers. If noise.qubit_count > 1 and the number of qubits in target_qubits is not the same as noise.qubit_count.

Examples

>>> circ = Circuit().x(0).y(1).z(0).x(1).cnot(0, 1)
>>> print(circ)

>>> noise = Noise.Depolarizing(probability=0.1)
>>> circ = Circuit().x(0).y(1).z(0).x(1).cnot(0, 1)
>>> print(circ.apply_initialization_noise(noise))

>>> circ = Circuit().x(0).y(1).z(0).x(1).cnot(0, 1)
>>> print(circ.apply_initialization_noise(noise, target_qubits=1))

>>> circ = Circuit()
>>> print(circ.apply_initialization_noise(noise, target_qubits=[0, 1]))

add(addable, *args, **kwargs)

Generic add method for adding item(s) to self. Any arguments that add_circuit() and / or add_instruction() and / or add_result_type supports are supported by this method. If adding a subroutine, check with that subroutines documentation to determine what input it allows.

Parameters:

addable (AddableTypes) – The item(s) to add to self. Default = None.

Return type:

Circuit

Returns:

Circuit – self

Raises:

TypeError – If addable is an unsupported type

See also

add_circuit()

add_instruction()

add_result_type()

Examples

>>> circ = Circuit().add([Instruction(Gate.H(), 4), Instruction(Gate.CNot(), [4, 5])])
>>> circ = Circuit().add([ResultType.StateVector()])

>>> circ = Circuit().h(4).cnot([4, 5])

>>> @circuit.subroutine()
>>> def bell_pair(target):
...     return Circuit().h(target[0]).cnot(target[0:2])
>>> circ = Circuit().add(bell_pair, [4, 5])

adjoint()

Returns the adjoint of this circuit.

This is the adjoint of every instruction of the circuit, in reverse order. Result types, and consequently basis rotations will stay in the same order at the end of the circuit.

Return type:

Circuit

Returns:

Circuit – The adjoint of the circuit.

diagram(circuit_diagram_class=<class 'braket.circuits.text_diagram_builders.unicode_circuit_diagram.UnicodeCircuitDiagram'>)

Get a diagram for the current circuit.

Parameters:

circuit_diagram_class (type) – A CircuitDiagram class that builds the diagram for this circuit. Default = AsciiCircuitDiagram.

Return type:

str

Returns:

str – An ASCII string circuit diagram.

to_ir(ir_type=IRType.JAQCD, serialization_properties=None, gate_definitions=None)

Converts the circuit into the canonical intermediate representation. If the circuit is sent over the wire, this method is called before it is sent.

Parameters:

• ir_type (IRType) – The IRType to use for converting the circuit object to its IR representation.

• serialization_properties (SerializationProperties | None) – The serialization properties to use while serializing the object to the IR representation. The serialization properties supplied must correspond to the supplied ir_type. Defaults to None.

• gate_definitions (dict[tuple[Gate, QubitSet], PulseSequence] | None) – The calibration data for the device. default: None.

Return type:

Program | Program

Returns:

OpenQasmProgram | JaqcdProgram – A representation of the circuit in the ir_type format.

Raises:

ValueError – If the supplied ir_type is not supported, or if the supplied serialization properties don’t correspond to the ir_type.

static from_ir(source, inputs=None)

Converts an OpenQASM program to a Braket Circuit object.

Parameters:

• source (str | OpenQasmProgram) – OpenQASM string.

• inputs (dict[str, io_type] | None) – Inputs to the circuit.

Return type:

Circuit

Returns:

Circuit – Braket Circuit implementing the OpenQASM program.

to_unitary()

Returns the unitary matrix representation of the entire circuit.

Note

The performance of this method degrades with qubit count. It might be slow for qubit count > 10.

Return type:

ndarray

Returns:

np.ndarray – A numpy array with shape (2 ^qubit_count, 2 ^qubit_count) representing the circuit as a unitary. For an empty circuit, an empty numpy array is returned (array([], dtype=complex))

Raises:

TypeError – If circuit is not composed only of Gate instances, i.e. a circuit with Noise operators will raise this error.

Examples

>>> circ = Circuit().h(0).cnot(0, 1)
>>> circ.to_unitary()
array([[ 0.70710678+0.j,  0.        +0.j,  0.70710678+0.j,
         0.        +0.j],
       [ 0.        +0.j,  0.70710678+0.j,  0.        +0.j,
         0.70710678+0.j],
       [ 0.        +0.j,  0.70710678+0.j,  0.        +0.j,
        -0.70710678+0.j],
       [ 0.70710678+0.j,  0.        +0.j, -0.70710678+0.j,
         0.        +0.j]])

property qubits_frozen: bool

Whether the circuit’s qubits are frozen, that is, cannot be remapped.

This may happen because the circuit contains compiler directives preventing compilation of a part of the circuit, which consequently means that none of the other qubits can be rewired either for the program to still make sense.

Type:

bool

property observables_simultaneously_measurable: bool

Whether the circuit’s observables are simultaneously measurable

If this is False, then the circuit can only be run when shots = 0, as sampling (shots > 0) measures the circuit in the observables’ shared eigenbasis.

Type:

bool

copy()

Return a shallow copy of the circuit.

Return type:

Circuit

Returns:

Circuit – A shallow copy of the circuit.

adjoint_gradient(*args, **kwargs) → SubroutineReturn

Registers this function into the circuit class.

Parameters:

• observable (Observable) – The expectation value of this observable is the function against which parameters in the gradient are differentiated.

• target (list[QubitSetInput] | None) – Target qubits that the result type is requested for. Each term in the target list should have the same number of qubits as the corresponding term in the observable. Default is None, which means the observable must operate only on 1 qubit and it is applied to all qubits in parallel.

• parameters (list[str | FreeParameter] | None) – The free parameters in the circuit to differentiate with respect to. Default: all.

Return type:

TypeVar(SubroutineReturn, Iterable[Instruction], Instruction, ResultType, Iterable[ResultType])

Returns:

ResultType – gradient computed via adjoint differentiation as a requested result type

Examples

>>> alpha, beta = FreeParameter("alpha"), FreeParameter("beta")
>>> circ = Circuit().h(0).h(1).rx(0, alpha).yy(0, 1, beta).adjoint_gradient(
>>>     observable=observables.Z(0), parameters=[alpha, beta]
>>> )

amplitude(*args, **kwargs) → SubroutineReturn

Registers this function into the circuit class.

Parameters:

state (list[str]) – list of quantum states as strings with “0” and “1”

Return type:

TypeVar(SubroutineReturn, Iterable[Instruction], Instruction, ResultType, Iterable[ResultType])

Returns:

ResultType – state vector as a requested result type

Examples

>>> circ = Circuit().amplitude(state=["01", "10"])

amplitude_damping(*args, **kwargs) → SubroutineReturn

Registers this function into the circuit class.

Parameters:

• target (QubitSetInput) – Target qubit(s).

• gamma (float) – decaying rate of the amplitude damping channel.

Return type:

TypeVar(SubroutineReturn, Iterable[Instruction], Instruction, ResultType, Iterable[ResultType])

Returns:

Iterable[Instruction] – Iterable of AmplitudeDamping instructions.

Examples

>>> circ = Circuit().amplitude_damping(0, gamma=0.1)

bit_flip(*args, **kwargs) → SubroutineReturn

Registers this function into the circuit class.

Parameters:

• target (QubitSetInput) – Target qubit(s)

• probability (float) – Probability of bit flipping.

Return type:

TypeVar(SubroutineReturn, Iterable[Instruction], Instruction, ResultType, Iterable[ResultType])

Returns:

Iterable[Instruction] – Iterable of BitFlip instructions.

Examples

>>> circ = Circuit().bit_flip(0, probability=0.1)

cc_prx(*args, **kwargs) → SubroutineReturn

Conditional PhaseRx gate.

Applies a rotation around the X-axis with a phase factor, conditioned on the value in a classical feedback register.

Parameters:

• target (QubitSetInput) – Target qubit(s).

• angle_1 (FreeParameterExpression | float) – First angle in radians.

• angle_2 (FreeParameterExpression | float) – Second angle in radians.

• feedback_key (int) – The integer feedback key that points to a measurement result.

Return type:

TypeVar(SubroutineReturn, Iterable[Instruction], Instruction, ResultType, Iterable[ResultType])

Returns:

Iterable[Instruction] – CCPRx instruction.

Examples

>>> circ = Circuit().cc_prx(0, 0.15, 0.25, 0)

ccnot(*args, **kwargs) → SubroutineReturn

CCNOT gate or Toffoli gate.

\[\begin{split}\mathtt{CCNOT} = \begin{bmatrix} 1 & 0 & 0 & 0 & 0 & 0 & 0 & 0 \\ 0 & 1 & 0 & 0 & 0 & 0 & 0 & 0 \\ 0 & 0 & 1 & 0 & 0 & 0 & 0 & 0 \\ 0 & 0 & 0 & 1 & 0 & 0 & 0 & 0 \\ 0 & 0 & 0 & 0 & 1 & 0 & 0 & 0 \\ 0 & 0 & 0 & 0 & 0 & 1 & 0 & 0 \\ 0 & 0 & 0 & 0 & 0 & 0 & 0 & 1 \\ 0 & 0 & 0 & 0 & 0 & 0 & 1 & 0 \\ \end{bmatrix}.\end{split}\]

Parameters:

• control1 (QubitInput) – Control qubit 1 index.

• control2 (QubitInput) – Control qubit 2 index.

• target (QubitInput) – Target qubit index.

• control (QubitSetInput | None) – Control qubit(s), in addition to control1 and control2. Default None.

• control_state (BasisStateInput | None) – Quantum state on which to control the operation. Must be a binary sequence of same length as number of qubits in control. Will be ignored if control is not present. May be represented as a string, list, or int. For example “0101”, [0, 1, 0, 1], 5 all represent controlling on qubits 0 and 2 being in the \|0⟩ state and qubits 1 and 3 being in the \|1⟩ state. Control state only applies to control qubits specified with the control argument, not control1 and control2. Default “1” * len(control).

• power (float) – Integer or fractional power to raise the gate to. Negative powers will be split into an inverse, accompanied by the positive power. Default 1.

Return type:

TypeVar(SubroutineReturn, Iterable[Instruction], Instruction, ResultType, Iterable[ResultType])

Returns:

Instruction – CCNot instruction.

Examples

>>> circ = Circuit().ccnot(0, 1, 2)

cnot(*args, **kwargs) → SubroutineReturn

Controlled NOT gate.

\[\begin{split}\mathtt{CNOT} = \begin{bmatrix} 1 & 0 & 0 & 0 \\ 0 & 1 & 0 & 0 \\ 0 & 0 & 0 & 1 \\ 0 & 0 & 1 & 0 \\ \end{bmatrix}.\end{split}\]

Parameters:

• control (QubitSetInput) – Control qubit(s). The last control qubit is absorbed into the target of the instruction.

• target (QubitInput) – Target qubit index.

• power (float) – Integer or fractional power to raise the gate to. Negative powers will be split into an inverse, accompanied by the positive power. Default 1.

Return type:

TypeVar(SubroutineReturn, Iterable[Instruction], Instruction, ResultType, Iterable[ResultType])

Returns:

Instruction – CNot instruction.

Examples

>>> circ = Circuit().cnot(0, 1)

cphaseshift(*args, **kwargs) → SubroutineReturn

Controlled phase shift gate.

\[\begin{split}\mathtt{CPhaseShift}(\phi) = \begin{bmatrix} 1 & 0 & 0 & 0 \\ 0 & 1 & 0 & 0 \\ 0 & 0 & 1 & 0 \\ 0 & 0 & 0 & e^{i \phi} \end{bmatrix}.\end{split}\]

Parameters:

• control (QubitSetInput) – Control qubit(s). The last control qubit is absorbed into the target of the instruction.

• target (QubitInput) – Target qubit index.

• angle (float | FreeParameterExpression) – angle in radians.

• power (float) – Integer or fractional power to raise the gate to. Negative powers will be split into an inverse, accompanied by the positive power. Default 1.

Return type:

TypeVar(SubroutineReturn, Iterable[Instruction], Instruction, ResultType, Iterable[ResultType])

Returns:

Instruction – CPhaseShift instruction.

Examples

>>> circ = Circuit().cphaseshift(0, 1, 0.15)

cphaseshift00(*args, **kwargs) → SubroutineReturn

Controlled phase shift gate for phasing the |00> state.

\[\begin{split}\mathtt{CPhaseShift00}(\phi) = \begin{bmatrix} e^{i \phi} & 0 & 0 & 0 \\ 0 & 1 & 0 & 0 \\ 0 & 0 & 1 & 0 \\ 0 & 0 & 0 & 1 \end{bmatrix}.\end{split}\]

Parameters:

• control (QubitSetInput) – Control qubit(s). The last control qubit is absorbed into the target of the instruction.

• target (QubitInput) – Target qubit index.

• angle (float | FreeParameterExpression) – angle in radians.

• power (float) – Integer or fractional power to raise the gate to. Negative powers will be split into an inverse, accompanied by the positive power. Default 1.

Return type:

TypeVar(SubroutineReturn, Iterable[Instruction], Instruction, ResultType, Iterable[ResultType])

Returns:

Instruction – CPhaseShift00 instruction.

Examples

>>> circ = Circuit().cphaseshift00(0, 1, 0.15)

cphaseshift01(*args, **kwargs) → SubroutineReturn

Controlled phase shift gate for phasing the |01> state.

\[\begin{split}\mathtt{CPhaseShift01}(\phi) = \begin{bmatrix} 1 & 0 & 0 & 0 \\ 0 & e^{i \phi} & 0 & 0 \\ 0 & 0 & 1 & 0 \\ 0 & 0 & 0 & 1 \end{bmatrix}.\end{split}\]

Parameters:

• control (QubitSetInput) – Control qubit(s). The last control qubit is absorbed into the target of the instruction.

• target (QubitInput) – Target qubit index.

• angle (float | FreeParameterExpression) – angle in radians.

• power (float) – Integer or fractional power to raise the gate to. Negative powers will be split into an inverse, accompanied by the positive power. Default 1.

Return type:

TypeVar(SubroutineReturn, Iterable[Instruction], Instruction, ResultType, Iterable[ResultType])

Returns:

Instruction – CPhaseShift01 instruction.

Examples

>>> circ = Circuit().cphaseshift01(0, 1, 0.15)

cphaseshift10(*args, **kwargs) → SubroutineReturn

Controlled phase shift gate for phasing the \|10> state.

\[\begin{split}\mathtt{CPhaseShift10}(\phi) = \begin{bmatrix} 1 & 0 & 0 & 0 \\ 0 & 1 & 0 & 0 \\ 0 & 0 & e^{i \phi} & 0 \\ 0 & 0 & 0 & 1 \end{bmatrix}.\end{split}\]

Parameters:

• control (QubitSetInput) – Control qubit(s). The last control qubit is absorbed into the target of the instruction.

• target (QubitInput) – Target qubit index.

• angle (float | FreeParameterExpression) – angle in radians.

• power (float) – Integer or fractional power to raise the gate to. Negative powers will be split into an inverse, accompanied by the positive power. Default 1.

Return type:

TypeVar(SubroutineReturn, Iterable[Instruction], Instruction, ResultType, Iterable[ResultType])

Returns:

Instruction – CPhaseShift10 instruction.

Examples

>>> circ = Circuit().cphaseshift10(0, 1, 0.15)

cswap(*args, **kwargs) → SubroutineReturn

Controlled Swap gate.

\[\begin{split}\mathtt{CSWAP} = \begin{bmatrix} 1 & 0 & 0 & 0 & 0 & 0 & 0 & 0 \\ 0 & 1 & 0 & 0 & 0 & 0 & 0 & 0 \\ 0 & 0 & 1 & 0 & 0 & 0 & 0 & 0 \\ 0 & 0 & 0 & 1 & 0 & 0 & 0 & 0 \\ 0 & 0 & 0 & 0 & 1 & 0 & 0 & 0 \\ 0 & 0 & 0 & 0 & 0 & 0 & 1 & 0 \\ 0 & 0 & 0 & 0 & 0 & 1 & 0 & 0 \\ 0 & 0 & 0 & 0 & 0 & 0 & 0 & 1 \\ \end{bmatrix}.\end{split}\]

Parameters:

• control (QubitSetInput) – Control qubit(s). The last control qubit is absorbed into the target of the instruction.

• target1 (QubitInput) – Target qubit 1 index.

• target2 (QubitInput) – Target qubit 2 index.

• power (float) – Integer or fractional power to raise the gate to. Negative powers will be split into an inverse, accompanied by the positive power. Default 1.

Return type:

TypeVar(SubroutineReturn, Iterable[Instruction], Instruction, ResultType, Iterable[ResultType])

Returns:

Instruction – CSwap instruction.

Examples

>>> circ = Circuit().cswap(0, 1, 2)

cv(*args, **kwargs) → SubroutineReturn

Controlled Sqrt of X gate.

\[\begin{split}\mathtt{CV} = \begin{bmatrix} 1 & 0 & 0 & 0 \\ 0 & 1 & 0 & 0 \\ 0 & 0 & 0.5+0.5i & 0.5-0.5i \\ 0 & 0 & 0.5-0.5i & 0.5+0.5i \end{bmatrix}.\end{split}\]

Parameters:

• control (QubitSetInput) – Control qubit(s). The last control qubit is absorbed into the target of the instruction.

• target (QubitInput) – Target qubit index.

• power (float) – Integer or fractional power to raise the gate to. Negative powers will be split into an inverse, accompanied by the positive power. Default 1.

Return type:

TypeVar(SubroutineReturn, Iterable[Instruction], Instruction, ResultType, Iterable[ResultType])

Returns:

Instruction – CV instruction.

Examples

>>> circ = Circuit().cv(0, 1)

cy(*args, **kwargs) → SubroutineReturn

Controlled Pauli-Y gate.

\[\begin{split}\mathtt{CY} = \begin{bmatrix} 1 & 0 & 0 & 0 \\ 0 & 1 & 0 & 0 \\ 0 & 0 & 0 & -i \\ 0 & 0 & i & 0 \end{bmatrix}.\end{split}\]

Parameters:

• control (QubitSetInput) – Control qubit(s). The last control qubit is absorbed into the target of the instruction.

• target (QubitInput) – Target qubit index.

• power (float) – Integer or fractional power to raise the gate to. Negative powers will be split into an inverse, accompanied by the positive power. Default 1.

Return type:

TypeVar(SubroutineReturn, Iterable[Instruction], Instruction, ResultType, Iterable[ResultType])

Returns:

Instruction – CY instruction.

Examples

>>> circ = Circuit().cy(0, 1)

cz(*args, **kwargs) → SubroutineReturn

Controlled Pauli-Z gate.

\[\begin{split}\mathtt{CZ} = \begin{bmatrix} 1 & 0 & 0 & 0 \\ 0 & 1 & 0 & 0 \\ 0 & 0 & 1 & 0 \\ 0 & 0 & 0 & -1 \end{bmatrix}.\end{split}\]

Parameters:

• control (QubitSetInput) – Control qubit(s). The last control qubit is absorbed into the target of the instruction.

• target (QubitInput) – Target qubit index.

• power (float) – Integer or fractional power to raise the gate to. Negative powers will be split into an inverse, accompanied by the positive power. Default 1.

Return type:

TypeVar(SubroutineReturn, Iterable[Instruction], Instruction, ResultType, Iterable[ResultType])

Returns:

Instruction – CZ instruction.

Examples

>>> circ = Circuit().cz(0, 1)

density_matrix(*args, **kwargs) → SubroutineReturn

Registers this function into the circuit class.

Parameters:

target (QubitSetInput | None) – The target qubits of the reduced density matrix. Default is None, and the full density matrix is returned.

Return type:

TypeVar(SubroutineReturn, Iterable[Instruction], Instruction, ResultType, Iterable[ResultType])

Returns:

ResultType – density matrix as a requested result type

Examples

>>> circ = Circuit().density_matrix(target=[0, 1])

depolarizing(*args, **kwargs) → SubroutineReturn

Registers this function into the circuit class.

Parameters:

• target (QubitSetInput) – Target qubit(s)

• probability (float) – Probability of depolarizing.

Return type:

TypeVar(SubroutineReturn, Iterable[Instruction], Instruction, ResultType, Iterable[ResultType])

Returns:

Iterable[Instruction] – Iterable of Depolarizing instructions.

Examples

>>> circ = Circuit().depolarizing(0, probability=0.1)

ecr(*args, **kwargs) → SubroutineReturn

An echoed RZX(pi/2) gate (ECR gate).

\[\begin{split}\mathtt{ECR} = \begin{bmatrix} 0 & 0 & 1 & i \\ 0 & 0 & i & 1 \\ 1 & -i & 0 & 0 \\ -i & 1 & 0 & 0 \end{bmatrix}.\end{split}\]

Parameters:

• target1 (QubitInput) – Target qubit 1 index.

• target2 (QubitInput) – Target qubit 2 index.

• control (QubitSetInput | None) – Control qubit(s). Default None.

• control_state (BasisStateInput | None) – Quantum state on which to control the operation. Must be a binary sequence of same length as number of qubits in control. Will be ignored if control is not present. May be represented as a string, list, or int. For example “0101”, [0, 1, 0, 1], 5 all represent controlling on qubits 0 and 2 being in the \|0⟩ state and qubits 1 and 3 being in the \|1⟩ state. Default “1” * len(control).

• power (float) – Integer or fractional power to raise the gate to. Negative powers will be split into an inverse, accompanied by the positive power. Default 1.

Return type:

TypeVar(SubroutineReturn, Iterable[Instruction], Instruction, ResultType, Iterable[ResultType])

Returns:

Instruction – ECR instruction.

Examples

>>> circ = Circuit().ecr(0, 1)

expectation(*args, **kwargs) → SubroutineReturn

Registers this function into the circuit class.

Parameters:

• observable (Observable) – the observable for the result type

• target (QubitSetInput | None) – Target qubits that the result type is requested for. Default is None, which means the observable must operate only on 1 qubit and it is applied to all qubits in parallel.

Return type:

TypeVar(SubroutineReturn, Iterable[Instruction], Instruction, ResultType, Iterable[ResultType])

Returns:

ResultType – expectation as a requested result type

Examples

>>> circ = Circuit().expectation(observable=observables.Z(0))

generalized_amplitude_damping(*args, **kwargs) → SubroutineReturn

Registers this function into the circuit class.

Parameters:

• target (QubitSetInput) – Target qubit(s).

• gamma (float) – The damping rate of the amplitude damping channel.

• probability (float) – Probability of the system being excited by the environment.

Return type:

TypeVar(SubroutineReturn, Iterable[Instruction], Instruction, ResultType, Iterable[ResultType])

Returns:

Iterable[Instruction] – Iterable of GeneralizedAmplitudeDamping instructions.

Examples

>>> circ = Circuit().generalized_amplitude_damping(0, gamma=0.1, probability=0.9)

gphase(*args, **kwargs) → SubroutineReturn

Global phase gate.

If the gate is applied with control/negative control modifiers, it is translated in an equivalent gate using the following definition: phaseshift(λ) = ctrl @ gphase(λ). The rightmost control qubit is used for the translation. If the polarity of the rightmost control modifier is negative, the following identity is used: negctrl @ gphase(λ) q = x q; ctrl @ gphase(λ) q; x q.

Unitary matrix:

\[\mathtt{gphase}(\gamma) = e^{i \gamma} I_1 = \begin{bmatrix} e^{i \gamma} \end{bmatrix}.\]

Parameters:

• angle (float | FreeParameterExpression) – Phase in radians.

• control (QubitSetInput | None) – Control qubit(s). Default None.

• control_state (BasisStateInput | None) – Quantum state on which to control the operation. Must be a binary sequence of same length as number of qubits in control. Will be ignored if control is not present. May be represented as a string, list, or int. For example “0101”, [0, 1, 0, 1], 5 all represent controlling on qubits 0 and 2 being in the \|0⟩ state and qubits 1 and 3 being in the \|1⟩ state. Default “1” * len(control).

• power (float) – Integer or fractional power to raise the gate to. Negative powers will be split into an inverse, accompanied by the positive power. Default 1.

Return type:

TypeVar(SubroutineReturn, Iterable[Instruction], Instruction, ResultType, Iterable[ResultType])

Returns:

Instruction | Iterable[Instruction] – GPhase instruction.

Examples

>>> circ = Circuit().gphase(0.45)

gpi(*args, **kwargs) → SubroutineReturn

IonQ GPi gate.

\[\begin{split}\mathtt{GPi}(\phi) = \begin{bmatrix} 0 & e^{-i \phi} \\ e^{i \phi} & 0 \end{bmatrix}.\end{split}\]

Parameters:

• target (QubitSetInput) – Target qubit(s).

• angle (float | FreeParameterExpression) – Angle in radians.

• control (QubitSetInput | None) – Control qubit(s). Default None.

• control_state (BasisStateInput | None) – Quantum state on which to control the operation. Must be a binary sequence of same length as number of qubits in control. Will be ignored if control is not present. May be represented as a string, list, or int. For example “0101”, [0, 1, 0, 1], 5 all represent controlling on qubits 0 and 2 being in the \|0⟩ state and qubits 1 and 3 being in the \|1⟩ state. Default “1” * len(control).

• power (float) – Integer or fractional power to raise the gate to. Negative powers will be split into an inverse, accompanied by the positive power. Default 1.

Return type:

TypeVar(SubroutineReturn, Iterable[Instruction], Instruction, ResultType, Iterable[ResultType])

Returns:

Iterable[Instruction] – GPi instruction.

Examples

>>> circ = Circuit().gpi(0, 0.15)

gpi2(*args, **kwargs) → SubroutineReturn

IonQ GPi2 gate.

\[\begin{split}\mathtt{GPi2}(\phi) = \frac{1}{\sqrt{2}} \begin{bmatrix} 1 & -i e^{-i \phi} \\ -i e^{i \phi} & 1 \end{bmatrix}.\end{split}\]

Parameters:

• target (QubitSetInput) – Target qubit(s).

• angle (float | FreeParameterExpression) – Angle in radians.

• control (QubitSetInput | None) – Control qubit(s). Default None.

• control_state (BasisStateInput | None) – Quantum state on which to control the operation. Must be a binary sequence of same length as number of qubits in control. Will be ignored if control is not present. May be represented as a string, list, or int. For example “0101”, [0, 1, 0, 1], 5 all represent controlling on qubits 0 and 2 being in the \|0⟩ state and qubits 1 and 3 being in the \|1⟩ state. Default “1” * len(control).

• power (float) – Integer or fractional power to raise the gate to. Negative powers will be split into an inverse, accompanied by the positive power. Default 1.

Return type:

TypeVar(SubroutineReturn, Iterable[Instruction], Instruction, ResultType, Iterable[ResultType])

Returns:

Iterable[Instruction] – GPi2 instruction.

Examples

>>> circ = Circuit().gpi2(0, 0.15)

h(*args, **kwargs) → SubroutineReturn

Hadamard gate.

Unitary matrix:

\[\begin{split}\mathtt{H} = \frac{1}{\sqrt{2}} \begin{bmatrix} 1 & 1 \\ 1 & -1 \end{bmatrix}.\end{split}\]

Parameters:

• target (QubitSetInput) – Target qubit(s)

• control (QubitSetInput | None) – Control qubit(s). Default None.

• control_state (BasisStateInput | None) – Quantum state on which to control the operation. Must be a binary sequence of same length as number of qubits in control. Will be ignored if control is not present. May be represented as a string, list, or int. For example “0101”, [0, 1, 0, 1], 5 all represent controlling on qubits 0 and 2 being in the \|0⟩ state and qubits 1 and 3 being in the \|1⟩ state. Default “1” * len(control).

• power (float) – Integer or fractional power to raise the gate to. Negative powers will be split into an inverse, accompanied by the positive power. Default 1.

Return type:

TypeVar(SubroutineReturn, Iterable[Instruction], Instruction, ResultType, Iterable[ResultType])

Returns:

Iterable[Instruction] – Iterable of H instructions.

Examples

>>> circ = Circuit().h(0)
>>> circ = Circuit().h([0, 1, 2])

i(*args, **kwargs) → SubroutineReturn

Identity gate.

Unitary matrix:

\[\begin{split}\mathtt{I} = \begin{bmatrix} 1 & 0 \\ 0 & 1 \end{bmatrix}.\end{split}\]

Parameters:

• target (QubitSetInput) – Target qubit(s)

• control (QubitSetInput | None) – Control qubit(s). Default None.

• control_state (BasisStateInput | None) – Quantum state on which to control the operation. Must be a binary sequence of same length as number of qubits in control. Will be ignored if control is not present. May be represented as a string, list, or int. For example “0101”, [0, 1, 0, 1], 5 all represent controlling on qubits 0 and 2 being in the \|0⟩ state and qubits 1 and 3 being in the \|1⟩ state. Default “1” * len(control).

• power (float) – Integer or fractional power to raise the gate to. Negative powers will be split into an inverse, accompanied by the positive power. Default 1.

Return type:

TypeVar(SubroutineReturn, Iterable[Instruction], Instruction, ResultType, Iterable[ResultType])

Returns:

Iterable[Instruction] – Iterable of I instructions.

Examples

>>> circ = Circuit().i(0)
>>> circ = Circuit().i([0, 1, 2])

iswap(*args, **kwargs) → SubroutineReturn

ISwap gate.

\[\begin{split}\mathtt{iSWAP} = \begin{bmatrix} 1 & 0 & 0 & 0 \\ 0 & 0 & i & 0 \\ 0 & i & 0 & 0 \\ 0 & 0 & 0 & 1 \\ \end{bmatrix}.\end{split}\]

Parameters:

• target1 (QubitInput) – Target qubit 1 index.

• target2 (QubitInput) – Target qubit 2 index.

• control (QubitSetInput | None) – Control qubit(s). Default None.

• control_state (BasisStateInput | None) – Quantum state on which to control the operation. Must be a binary sequence of same length as number of qubits in control. Will be ignored if control is not present. May be represented as a string, list, or int. For example “0101”, [0, 1, 0, 1], 5 all represent controlling on qubits 0 and 2 being in the \|0⟩ state and qubits 1 and 3 being in the \|1⟩ state. Default “1” * len(control).

• power (float) – Integer or fractional power to raise the gate to. Negative powers will be split into an inverse, accompanied by the positive power. Default 1.

Return type:

TypeVar(SubroutineReturn, Iterable[Instruction], Instruction, ResultType, Iterable[ResultType])

Returns:

Instruction – ISwap instruction.

Examples

>>> circ = Circuit().iswap(0, 1)

kraus(*args, **kwargs) → SubroutineReturn

Registers this function into the circuit class.

Parameters:

• targets (QubitSetInput) – Target qubit(s)

• matrices (Iterable[array]) – Matrices that define a general noise channel.

• display_name (str) – The display name.

Return type:

TypeVar(SubroutineReturn, Iterable[Instruction], Instruction, ResultType, Iterable[ResultType])

Returns:

Iterable[Instruction] – Iterable of Kraus instructions.

Examples

>>> K0 = np.eye(4) * np.sqrt(0.9)
>>> K1 = np.kron([[1.0, 0.0], [0.0, 1.0]], [[0.0, 1.0], [1.0, 0.0]]) * np.sqrt(0.1)
>>> circ = Circuit().kraus([1, 0], matrices=[K0, K1])

measure_ff(*args, **kwargs) → SubroutineReturn

Measure and store result for feed-forward operations.

Performs a measurement on the target qubit and stores the result in a classical feedback register for later use in conditional operations.

Parameters:

• target (QubitSetInput) – Target qubit(s).

• feedback_key (int) – The integer feedback key that points to a measurement result.

Return type:

TypeVar(SubroutineReturn, Iterable[Instruction], Instruction, ResultType, Iterable[ResultType])

Returns:

Iterable[Instruction] – MeasureFF instruction.

Examples

>>> circ = Circuit().measure_ff(0, 0)

ms(*args, **kwargs) → SubroutineReturn

IonQ Mølmer-Sørensen gate.

\[\begin{split}&\mathtt{MS}(\phi_0, \phi_1, \theta) =\\ &\begin{bmatrix} \cos{\frac{\theta}{2}} & 0 & 0 & -ie^{-i (\phi_0 + \phi_1)}\sin{\frac{\theta}{2}} \\ 0 & \cos{\frac{\theta}{2}} & -ie^{-i (\phi_0 - \phi_1)}\sin{\frac{\theta}{2}} & 0 \\ 0 & -ie^{i (\phi_0 - \phi_1)}\sin{\frac{\theta}{2}} & \cos{\frac{\theta}{2}} & 0 \\ -ie^{i (\phi_0 + \phi_1)}\sin{\frac{\theta}{2}} & 0 & 0 & \cos{\frac{\theta}{2}} \end{bmatrix}.\end{split}\]

Parameters:

• target1 (QubitInput) – Target qubit 1 index.

• target2 (QubitInput) – Target qubit 2 index.

• angle_1 (float | FreeParameterExpression) – angle in radians.

• angle_2 (float | FreeParameterExpression) – angle in radians.

• angle_3 (float | FreeParameterExpression) – angle in radians.

• control (QubitSetInput | None) – Control qubit(s). Default None.

• control_state (BasisStateInput | None) – Quantum state on which to control the operation. Must be a binary sequence of same length as number of qubits in control. Will be ignored if control is not present. May be represented as a string, list, or int. For example “0101”, [0, 1, 0, 1], 5 all represent controlling on qubits 0 and 2 being in the \|0⟩ state and qubits 1 and 3 being in the \|1⟩ state. Default “1” * len(control).

• power (float) – Integer or fractional power to raise the gate to. Negative powers will be split into an inverse, accompanied by the positive power. Default 1.

Return type:

TypeVar(SubroutineReturn, Iterable[Instruction], Instruction, ResultType, Iterable[ResultType])

Returns:

Iterable[Instruction] – MS instruction.

Examples

>>> circ = Circuit().ms(0, 1, 0.15, 0.34)

pauli_channel(*args, **kwargs) → SubroutineReturn

Registers this function into the circuit class.

Parameters:

• target (QubitSetInput) – Target qubit(s) probability list[float]: Probabilities for the Pauli X, Y and Z noise happening in the Kraus channel.

• probX (float) – X rotation probability.

• probY (float) – Y rotation probability.

• probZ (float) – Z rotation probability.

Return type:

TypeVar(SubroutineReturn, Iterable[Instruction], Instruction, ResultType, Iterable[ResultType])

Returns:

Iterable[Instruction] – Iterable of PauliChannel instructions.

Examples

>>> circ = Circuit().pauli_channel(0, probX=0.1, probY=0.2, probZ=0.3)

phase_damping(*args, **kwargs) → SubroutineReturn

Registers this function into the circuit class.

Parameters:

• target (QubitSetInput) – Target qubit(s)

• gamma (float) – Probability of phase damping.

Return type:

TypeVar(SubroutineReturn, Iterable[Instruction], Instruction, ResultType, Iterable[ResultType])

Returns:

Iterable[Instruction] – Iterable of PhaseDamping instructions.

Examples

>>> circ = Circuit().phase_damping(0, gamma=0.1)

phase_flip(*args, **kwargs) → SubroutineReturn

Registers this function into the circuit class.

Parameters:

• target (QubitSetInput) – Target qubit(s)

• probability (float) – Probability of phase flipping.

Return type:

TypeVar(SubroutineReturn, Iterable[Instruction], Instruction, ResultType, Iterable[ResultType])

Returns:

Iterable[Instruction] – Iterable of PhaseFlip instructions.

Examples

>>> circ = Circuit().phase_flip(0, probability=0.1)

phaseshift(*args, **kwargs) → SubroutineReturn

Phase shift gate.

\[\begin{split}\mathtt{PhaseShift}(\phi) = \begin{bmatrix} 1 & 0 \\ 0 & e^{i \phi} \end{bmatrix}\end{split}\]

Parameters:

• target (QubitSetInput) – Target qubit(s).

• angle (float | FreeParameterExpression) – angle in radians.

• control (QubitSetInput | None) – Control qubit(s). Default None.

• control_state (BasisStateInput | None) – Quantum state on which to control the operation. Must be a binary sequence of same length as number of qubits in control. Will be ignored if control is not present. May be represented as a string, list, or int. For example “0101”, [0, 1, 0, 1], 5 all represent controlling on qubits 0 and 2 being in the \|0⟩ state and qubits 1 and 3 being in the \|1⟩ state. Default “1” * len(control).

• power (float) – Integer or fractional power to raise the gate to. Negative powers will be split into an inverse, accompanied by the positive power. Default 1.

Return type:

TypeVar(SubroutineReturn, Iterable[Instruction], Instruction, ResultType, Iterable[ResultType])

Returns:

Iterable[Instruction] – PhaseShift instruction.

Examples

>>> circ = Circuit().phaseshift(0, 0.15)

probability(*args, **kwargs) → SubroutineReturn

Registers this function into the circuit class.

Parameters:

target (QubitSetInput | None) – The target qubits that the result type is requested for. Default is None, which means all qubits for the circuit.

Return type:

TypeVar(SubroutineReturn, Iterable[Instruction], Instruction, ResultType, Iterable[ResultType])

Returns:

ResultType – probability as a requested result type

Examples

>>> circ = Circuit().probability(target=[0, 1])

prx(*args, **kwargs) → SubroutineReturn

PhaseRx gate.

\[\begin{split}\mathtt{PRx}(\theta,\phi) = \begin{bmatrix} \cos{(\theta / 2)} & -i e^{-i \phi} \sin{(\theta / 2)} \\ -i e^{i \phi} \sin{(\theta / 2)} & \cos{(\theta / 2)} \end{bmatrix}.\end{split}\]

Parameters:

• target (QubitSetInput) – Target qubit(s).

• angle_1 (float | FreeParameterExpression) – First angle in radians.

• angle_2 (float | FreeParameterExpression) – Second angle in radians.

• control (QubitSetInput | None) – Control qubit(s). Default None.

• control_state (BasisStateInput | None) – Quantum state on which to control the operation. Must be a binary sequence of same length as number of qubits in control. Will be ignored if control is not present. May be represented as a string, list, or int. For example “0101”, [0, 1, 0, 1], 5 all represent controlling on qubits 0 and 2 being in the \|0⟩ state and qubits 1 and 3 being in the \|1⟩ state. Default “1” * len(control).

• power (float) – Integer or fractional power to raise the gate to. Negative powers will be split into an inverse, accompanied by the positive power. Default 1.

Return type:

TypeVar(SubroutineReturn, Iterable[Instruction], Instruction, ResultType, Iterable[ResultType])

Returns:

Iterable[Instruction] – PhaseRx instruction.

Examples

>>> circ = Circuit().prx(0, 0.15, 0.25)

pswap(*args, **kwargs) → SubroutineReturn

PSwap gate.

\[\begin{split}\mathtt{PSWAP}(\phi) = \begin{bmatrix} 1 & 0 & 0 & 0 \\ 0 & 0 & e^{i \phi} & 0 \\ 0 & e^{i \phi} & 0 & 0 \\ 0 & 0 & 0 & 1 \\ \end{bmatrix}.\end{split}\]

Parameters:

• target1 (QubitInput) – Target qubit 1 index.

• target2 (QubitInput) – Target qubit 2 index.

• angle (float | FreeParameterExpression) – angle in radians.

• control (QubitSetInput | None) – Control qubit(s). Default None.

• control_state (BasisStateInput | None) – Quantum state on which to control the operation. Must be a binary sequence of same length as number of qubits in control. Will be ignored if control is not present. May be represented as a string, list, or int. For example “0101”, [0, 1, 0, 1], 5 all represent controlling on qubits 0 and 2 being in the \|0⟩ state and qubits 1 and 3 being in the \|1⟩ state. Default “1” * len(control).

• power (float) – Integer or fractional power to raise the gate to. Negative powers will be split into an inverse, accompanied by the positive power. Default 1.

Return type:

TypeVar(SubroutineReturn, Iterable[Instruction], Instruction, ResultType, Iterable[ResultType])

Returns:

Instruction – PSwap instruction.

Examples

>>> circ = Circuit().pswap(0, 1, 0.15)

pulse_gate(*args, **kwargs) → SubroutineReturn

Arbitrary pulse gate which provides the ability to embed custom pulse sequences

within circuits.

Parameters:

• targets (QubitSet) – Target qubits. Note: These are only for representational purposes. The actual targets are determined by the frames used in the pulse sequence.

• pulse_sequence (PulseSequence) – PulseSequence to embed within the circuit.

• display_name (str) – Name to be used for an instance of this pulse gate for circuit diagrams. Defaults to PG.

• control (QubitSetInput | None) – Control qubit(s). Default None.

• control_state (BasisStateInput | None) – Quantum state on which to control the operation. Must be a binary sequence of same length as number of qubits in control. Will be ignored if control is not present. May be represented as a string, list, or int. For example “0101”, [0, 1, 0, 1], 5 all represent controlling on qubits 0 and 2 being in the \|0⟩ state and qubits 1 and 3 being in the \|1⟩ state. Default “1” * len(control).

• power (float) – Integer or fractional power to raise the gate to. Negative powers will be split into an inverse, accompanied by the positive power. Default 1.

Return type:

TypeVar(SubroutineReturn, Iterable[Instruction], Instruction, ResultType, Iterable[ResultType])

Returns:

Instruction – Pulse gate instruction.

Examples

>>> pulse_seq = PulseSequence().set_frequency(frame, frequency)....
>>> circ = Circuit().pulse_gate(pulse_sequence=pulse_seq, targets=[0])

rx(*args, **kwargs) → SubroutineReturn

X-axis rotation gate.

\[\begin{split}\mathtt{R_x}(\phi) = \begin{bmatrix} \cos{(\phi/2)} & -i \sin{(\phi/2)} \\ -i \sin{(\phi/2)} & \cos{(\phi/2)} \end{bmatrix}.\end{split}\]

Parameters:

• target (QubitSetInput) – Target qubit(s).

• angle (float | FreeParameterExpression) – Angle in radians.

• control (QubitSetInput | None) – Control qubit(s). Default None.

• control_state (BasisStateInput | None) – Quantum state on which to control the operation. Must be a binary sequence of same length as number of qubits in control. Will be ignored if control is not present. May be represented as a string, list, or int. For example “0101”, [0, 1, 0, 1], 5 all represent controlling on qubits 0 and 2 being in the \|0⟩ state and qubits 1 and 3 being in the \|1⟩ state. Default “1” * len(control).

• power (float) – Integer or fractional power to raise the gate to. Negative powers will be split into an inverse, accompanied by the positive power. Default 1.

Return type:

TypeVar(SubroutineReturn, Iterable[Instruction], Instruction, ResultType, Iterable[ResultType])

Returns:

Iterable[Instruction] – Rx instruction.

Examples

>>> circ = Circuit().rx(0, 0.15)

ry(*args, **kwargs) → SubroutineReturn

Y-axis rotation gate.

\[\begin{split}\mathtt{R_y}(\phi) = \begin{bmatrix} \cos{(\phi/2)} & -\sin{(\phi/2)} \\ \sin{(\phi/2)} & \cos{(\phi/2)} \end{bmatrix}.\end{split}\]

Parameters:

• target (QubitSetInput) – Target qubit(s).

• angle (float | FreeParameterExpression) – Angle in radians.

• control (QubitSetInput | None) – Control qubit(s). Default None.

• control_state (BasisStateInput | None) – Quantum state on which to control the operation. Must be a binary sequence of same length as number of qubits in control. Will be ignored if control is not present. May be represented as a string, list, or int. For example “0101”, [0, 1, 0, 1], 5 all represent controlling on qubits 0 and 2 being in the \|0⟩ state and qubits 1 and 3 being in the \|1⟩ state. Default “1” * len(control).

• power (float) – Integer or fractional power to raise the gate to. Negative powers will be split into an inverse, accompanied by the positive power. Default 1.

Return type:

TypeVar(SubroutineReturn, Iterable[Instruction], Instruction, ResultType, Iterable[ResultType])

Returns:

Iterable[Instruction] – Rx instruction.

Examples

>>> circ = Circuit().ry(0, 0.15)

rz(*args, **kwargs) → SubroutineReturn

Z-axis rotation gate.

\[\begin{split}\mathtt{R_z}(\phi) = \begin{bmatrix} e^{-i \phi/2} & 0 \\ 0 & e^{i \phi/2} \end{bmatrix}.\end{split}\]

Parameters:

• target (QubitSetInput) – Target qubit(s).

• angle (float | FreeParameterExpression) – Angle in radians.

• control (QubitSetInput | None) – Control qubit(s). Default None.

• control_state (BasisStateInput | None) – Quantum state on which to control the operation. Must be a binary sequence of same length as number of qubits in control. Will be ignored if control is not present. May be represented as a string, list, or int. For example “0101”, [0, 1, 0, 1], 5 all represent controlling on qubits 0 and 2 being in the \|0⟩ state and qubits 1 and 3 being in the \|1⟩ state. Default “1” * len(control).

• power (float) – Integer or fractional power to raise the gate to. Negative powers will be split into an inverse, accompanied by the positive power. Default 1.

Return type:

TypeVar(SubroutineReturn, Iterable[Instruction], Instruction, ResultType, Iterable[ResultType])

Returns:

Iterable[Instruction] – Rx instruction.

Examples

>>> circ = Circuit().rz(0, 0.15)

s(*args, **kwargs) → SubroutineReturn

S gate.

\[\begin{split}\mathtt{S} = \begin{bmatrix} 1 & 0 \\ 0 & i \end{bmatrix}.\end{split}\]

Parameters:

• target (QubitSetInput) – Target qubit(s)

• control (QubitSetInput | None) – Control qubit(s). Default None.

• control_state (BasisStateInput | None) – Quantum state on which to control the operation. Must be a binary sequence of same length as number of qubits in control. Will be ignored if control is not present. May be represented as a string, list, or int. For example “0101”, [0, 1, 0, 1], 5 all represent controlling on qubits 0 and 2 being in the \|0⟩ state and qubits 1 and 3 being in the \|1⟩ state. Default “1” * len(control).

• power (float) – Integer or fractional power to raise the gate to. Negative powers will be split into an inverse, accompanied by the positive power. Default 1.

Return type:

TypeVar(SubroutineReturn, Iterable[Instruction], Instruction, ResultType, Iterable[ResultType])

Returns:

Iterable[Instruction] – Iterable of S instructions.

Examples

>>> circ = Circuit().s(0)
>>> circ = Circuit().s([0, 1, 2])

sample(*args, **kwargs) → SubroutineReturn

Registers this function into the circuit class.

Parameters:

• observable (Observable) – the observable for the result type

• target (QubitSetInput | None) – Target qubits that the result type is requested for. Default is None, which means the observable must operate only on 1 qubit and it is applied to all qubits in parallel.

Return type:

TypeVar(SubroutineReturn, Iterable[Instruction], Instruction, ResultType, Iterable[ResultType])

Returns:

ResultType – sample as a requested result type

Examples

>>> circ = Circuit().sample(observable=observables.Z(0))

si(*args, **kwargs) → SubroutineReturn

Conjugate transpose of S gate.

\[\begin{split}\mathtt{S}^\dagger = \begin{bmatrix} 1 & 0 \\ 0 & -i \end{bmatrix}.\end{split}\]

Parameters:

• target (QubitSetInput) – Target qubit(s)

• control (QubitSetInput | None) – Control qubit(s). Default None.

• control_state (BasisStateInput | None) – Quantum state on which to control the operation. Must be a binary sequence of same length as number of qubits in control. Will be ignored if control is not present. May be represented as a string, list, or int. For example “0101”, [0, 1, 0, 1], 5 all represent controlling on qubits 0 and 2 being in the \|0⟩ state and qubits 1 and 3 being in the \|1⟩ state. Default “1” * len(control).

• power (float) – Integer or fractional power to raise the gate to. Negative powers will be split into an inverse, accompanied by the positive power. Default 1.

Return type:

TypeVar(SubroutineReturn, Iterable[Instruction], Instruction, ResultType, Iterable[ResultType])

Returns:

Iterable[Instruction] – Iterable of Si instructions.

Examples

>>> circ = Circuit().si(0)
>>> circ = Circuit().si([0, 1, 2])

state_vector(*args, **kwargs) → SubroutineReturn

Registers this function into the circuit class.

Return type:

TypeVar(SubroutineReturn, Iterable[Instruction], Instruction, ResultType, Iterable[ResultType])

Returns:

ResultType – state vector as a requested result type

Examples

>>> circ = Circuit().state_vector()

swap(*args, **kwargs) → SubroutineReturn

Swap gate.

\[\begin{split}\mathtt{SWAP} = \begin{bmatrix} 1 & 0 & 0 & 0 \\ 0 & 0 & 1 & 0 \\ 0 & 1 & 0 & 0 \\ 0 & 0 & 0 & 1 \\ \end{bmatrix}.\end{split}\]

Parameters:

• target1 (QubitInput) – Target qubit 1 index.

• target2 (QubitInput) – Target qubit 2 index.

• control (QubitSetInput | None) – Control qubit(s). Default None.

• control_state (BasisStateInput | None) – Quantum state on which to control the operation. Must be a binary sequence of same length as number of qubits in control. Will be ignored if control is not present. May be represented as a string, list, or int. For example “0101”, [0, 1, 0, 1], 5 all represent controlling on qubits 0 and 2 being in the \|0⟩ state and qubits 1 and 3 being in the \|1⟩ state. Default “1” * len(control).

• power (float) – Integer or fractional power to raise the gate to. Negative powers will be split into an inverse, accompanied by the positive power. Default 1.

Return type:

TypeVar(SubroutineReturn, Iterable[Instruction], Instruction, ResultType, Iterable[ResultType])

Returns:

Instruction – Swap instruction.

Examples

>>> circ = Circuit().swap(0, 1)

t(*args, **kwargs) → SubroutineReturn

T gate.

\[\begin{split}\mathtt{T} = \begin{bmatrix} 1 & 0 \\ 0 & e^{i \pi/4} \end{bmatrix}.\end{split}\]

Parameters:

• target (QubitSetInput) – Target qubit(s)

• control (QubitSetInput | None) – Control qubit(s). Default None.

• control_state (BasisStateInput | None) – Quantum state on which to control the operation. Must be a binary sequence of same length as number of qubits in control. Will be ignored if control is not present. May be represented as a string, list, or int. For example “0101”, [0, 1, 0, 1], 5 all represent controlling on qubits 0 and 2 being in the \|0⟩ state and qubits 1 and 3 being in the \|1⟩ state. Default “1” * len(control).

• power (float) – Integer or fractional power to raise the gate to. Negative powers will be split into an inverse, accompanied by the positive power. Default 1.

Return type:

TypeVar(SubroutineReturn, Iterable[Instruction], Instruction, ResultType, Iterable[ResultType])

Returns:

Iterable[Instruction] – Iterable of T instructions.

Examples

>>> circ = Circuit().t(0)
>>> circ = Circuit().t([0, 1, 2])

ti(*args, **kwargs) → SubroutineReturn

Conjugate transpose of T gate.

\[\begin{split}\mathtt{T}^\dagger = \begin{bmatrix} 1 & 0 \\ 0 & e^{-i \pi/4} \end{bmatrix}.\end{split}\]

Parameters:

• target (QubitSetInput) – Target qubit(s)

• control (QubitSetInput | None) – Control qubit(s). Default None.

• control_state (BasisStateInput | None) – Quantum state on which to control the operation. Must be a binary sequence of same length as number of qubits in control. Will be ignored if control is not present. May be represented as a string, list, or int. For example “0101”, [0, 1, 0, 1], 5 all represent controlling on qubits 0 and 2 being in the \|0⟩ state and qubits 1 and 3 being in the \|1⟩ state. Default “1” * len(control).

• power (float) – Integer or fractional power to raise the gate to. Negative powers will be split into an inverse, accompanied by the positive power. Default 1.

Return type:

TypeVar(SubroutineReturn, Iterable[Instruction], Instruction, ResultType, Iterable[ResultType])

Returns:

Iterable[Instruction] – Iterable of Ti instructions.

Examples

>>> circ = Circuit().ti(0)
>>> circ = Circuit().ti([0, 1, 2])

two_qubit_dephasing(*args, **kwargs) → SubroutineReturn

Registers this function into the circuit class.

Parameters:

• target1 (QubitInput) – Target qubit 1.

• target2 (QubitInput) – Target qubit 2.

• probability (float) – Probability of two-qubit dephasing.

Return type:

TypeVar(SubroutineReturn, Iterable[Instruction], Instruction, ResultType, Iterable[ResultType])

Returns:

Iterable[Instruction] – Iterable of Dephasing instructions.

Examples

>>> circ = Circuit().two_qubit_dephasing(0, 1, probability=0.1)

two_qubit_depolarizing(*args, **kwargs) → SubroutineReturn

Registers this function into the circuit class.

Parameters:

• target1 (QubitInput) – Target qubit 1.

• target2 (QubitInput) – Target qubit 2.

• probability (float) – Probability of two-qubit depolarizing.

Return type:

TypeVar(SubroutineReturn, Iterable[Instruction], Instruction, ResultType, Iterable[ResultType])

Returns:

Iterable[Instruction] – Iterable of Depolarizing instructions.

Examples

>>> circ = Circuit().two_qubit_depolarizing(0, 1, probability=0.1)

two_qubit_pauli_channel(*args, **kwargs) → SubroutineReturn

Registers this function into the circuit class.

Parameters:

• target1 (QubitInput) – Target qubit 1.

• target2 (QubitInput) – Target qubit 2.

• probabilities (dict[str, float]) – Probability of two-qubit Pauli channel.

Return type:

TypeVar(SubroutineReturn, Iterable[Instruction], Instruction, ResultType, Iterable[ResultType])

Returns:

Iterable[Instruction] – Iterable of Depolarizing instructions.

Examples

>>> circ = Circuit().two_qubit_pauli_channel(0, 1, {"XX": 0.1})

u(*args, **kwargs) → SubroutineReturn

Generalized single-qubit rotation gate.

Unitary matrix:

\[\begin{split}\mathtt{U}(\theta, \phi, \lambda) = \begin{bmatrix} \cos{(\theta/2)} & -e^{i \lambda} \sin{(\theta/2)} \\ e^{i \phi} \sin{(\theta/2)} & e^{i (\phi + \lambda)} \cos{(\theta/2)} \end{bmatrix}.\end{split}\]

Parameters:

• target (QubitSetInput) – Target qubit(s)

• angle_1 (float | FreeParameterExpression) – theta angle in radians.

• angle_2 (float | FreeParameterExpression) – phi angle in radians.

• angle_3 (float | FreeParameterExpression) – lambda angle in radians.

• control (QubitSetInput | None) – Control qubit(s). Default None.

• control_state (BasisStateInput | None) – Quantum state on which to control the operation. Must be a binary sequence of same length as number of qubits in control. Will be ignored if control is not present. May be represented as a string, list, or int. For example “0101”, [0, 1, 0, 1], 5 all represent controlling on qubits 0 and 2 being in the \|0⟩ state and qubits 1 and 3 being in the \|1⟩ state. Default “1” * len(control).

• power (float) – Integer or fractional power to raise the gate to. Negative powers will be split into an inverse, accompanied by the positive power. Default 1.

Return type:

TypeVar(SubroutineReturn, Iterable[Instruction], Instruction, ResultType, Iterable[ResultType])

Returns:

Iterable[Instruction] – U instruction.

Examples

>>> circ = Circuit().u(0, 0.15, 0.34, 0.52)

unitary(*args, **kwargs) → SubroutineReturn

Arbitrary unitary gate.

Parameters:

• targets (QubitSet) – Target qubits.

• matrix (numpy.ndarray) – Unitary matrix which defines the gate. Matrix should be compatible with the supplied targets, with 2 ** len(targets) == matrix.shape[0].

• display_name (str) – Name to be used for an instance of this unitary gate for circuit diagrams. Defaults to U.

Return type:

TypeVar(SubroutineReturn, Iterable[Instruction], Instruction, ResultType, Iterable[ResultType])

Returns:

Instruction – Unitary instruction.

Raises:

ValueError – If matrix is not a two-dimensional square matrix, or has a dimension length that is not compatible with the targets, or is not unitary,

Examples

>>> circ = Circuit().unitary(matrix=np.array([[0, 1], [1, 0]]), targets=[0])

v(*args, **kwargs) → SubroutineReturn

Square root of X gate (V gate).

\[\begin{split}\mathtt{V} = \frac{1}{2}\begin{bmatrix} 1+i & 1-i \\ 1-i & 1+i \end{bmatrix}.\end{split}\]

Parameters:

• target (QubitSetInput) – Target qubit(s)

• control (QubitSetInput | None) – Control qubit(s). Default None.

• control_state (BasisStateInput | None) – Quantum state on which to control the operation. Must be a binary sequence of same length as number of qubits in control. Will be ignored if control is not present. May be represented as a string, list, or int. For example “0101”, [0, 1, 0, 1], 5 all represent controlling on qubits 0 and 2 being in the \|0⟩ state and qubits 1 and 3 being in the \|1⟩ state. Default “1” * len(control).

• power (float) – Integer or fractional power to raise the gate to. Negative powers will be split into an inverse, accompanied by the positive power. Default 1.

Return type:

TypeVar(SubroutineReturn, Iterable[Instruction], Instruction, ResultType, Iterable[ResultType])

Returns:

Iterable[Instruction] – Iterable of V instructions.

Examples

>>> circ = Circuit().v(0)
>>> circ = Circuit().v([0, 1, 2])

variance(*args, **kwargs) → SubroutineReturn

Registers this function into the circuit class.

Parameters:

• observable (Observable) – the observable for the result type

• target (QubitSetInput | None) – Target qubits that the result type is requested for. Default is None, which means the observable must only operate on 1 qubit and it will be applied to all qubits in parallel

Return type:

TypeVar(SubroutineReturn, Iterable[Instruction], Instruction, ResultType, Iterable[ResultType])

Returns:

ResultType – variance as a requested result type

Examples

>>> circ = Circuit().variance(observable=observables.Z(0))

vi(*args, **kwargs) → SubroutineReturn

Conjugate transpose of square root of X gate (conjugate transpose of V).

\[\begin{split}\mathtt{V}^\dagger = \frac{1}{2}\begin{bmatrix} 1-i & 1+i \\ 1+i & 1-i \end{bmatrix}.\end{split}\]

Parameters:

• target (QubitSetInput) – Target qubit(s)

• control (QubitSetInput | None) – Control qubit(s). Default None.

• control_state (BasisStateInput | None) – Quantum state on which to control the operation. Must be a binary sequence of same length as number of qubits in control. Will be ignored if control is not present. May be represented as a string, list, or int. For example “0101”, [0, 1, 0, 1], 5 all represent controlling on qubits 0 and 2 being in the \|0⟩ state and qubits 1 and 3 being in the \|1⟩ state. Default “1” * len(control).

• power (float) – Integer or fractional power to raise the gate to. Negative powers will be split into an inverse, accompanied by the positive power. Default 1.

Return type:

TypeVar(SubroutineReturn, Iterable[Instruction], Instruction, ResultType, Iterable[ResultType])

Returns:

Iterable[Instruction] – Iterable of Vi instructions.

Examples

>>> circ = Circuit().vi(0)
>>> circ = Circuit().vi([0, 1, 2])

x(*args, **kwargs) → SubroutineReturn

Pauli-X gate.

Unitary matrix:

\[\begin{split}\mathtt{X} = \begin{bmatrix} 0 & 1 \\ 1 & 0 \end{bmatrix}.\end{split}\]

Parameters:

• target (QubitSetInput) – Target qubit(s)

• control (QubitSetInput | None) – Control qubit(s). Default None.

• control_state (BasisStateInput | None) – Quantum state on which to control the operation. Must be a binary sequence of same length as number of qubits in control. Will be ignored if control is not present. May be represented as a string, list, or int. For example “0101”, [0, 1, 0, 1], 5 all represent controlling on qubits 0 and 2 being in the \|0⟩ state and qubits 1 and 3 being in the \|1⟩ state. Default “1” * len(control).

• power (float) – Integer or fractional power to raise the gate to. Negative powers will be split into an inverse, accompanied by the positive power. Default 1.

Return type:

TypeVar(SubroutineReturn, Iterable[Instruction], Instruction, ResultType, Iterable[ResultType])

Returns:

Iterable[Instruction] – Iterable of X instructions.

Examples

>>> circ = Circuit().x(0)
>>> circ = Circuit().x([0, 1, 2])

xx(*args, **kwargs) → SubroutineReturn

Ising XX coupling gate.

\[\begin{split}\mathtt{XX}(\phi) = \begin{bmatrix} \cos{(\phi/2)} & 0 & 0 & -i \sin{(\phi/2)} \\ 0 & \cos{(\phi/2)} & -i \sin{(\phi/2)} & 0 \\ 0 & -i \sin{(\phi/2)} & \cos{(\phi/2)} & 0 \\ -i \sin{(\phi/2)} & 0 & 0 & \cos{(\phi/2)} \end{bmatrix}.\end{split}\]

Parameters:

• target1 (QubitInput) – Target qubit 1 index.

• target2 (QubitInput) – Target qubit 2 index.

• angle (float | FreeParameterExpression) – angle in radians.

• control (QubitSetInput | None) – Control qubit(s). Default None.

• control_state (BasisStateInput | None) – Quantum state on which to control the operation. Must be a binary sequence of same length as number of qubits in control. Will be ignored if control is not present. May be represented as a string, list, or int. For example “0101”, [0, 1, 0, 1], 5 all represent controlling on qubits 0 and 2 being in the \|0⟩ state and qubits 1 and 3 being in the \|1⟩ state. Default “1” * len(control).

• power (float) – Integer or fractional power to raise the gate to. Negative powers will be split into an inverse, accompanied by the positive power. Default 1.

Return type:

TypeVar(SubroutineReturn, Iterable[Instruction], Instruction, ResultType, Iterable[ResultType])

Returns:

Instruction – XX instruction.

Examples

>>> circ = Circuit().xx(0, 1, 0.15)

xy(*args, **kwargs) → SubroutineReturn

XY gate.

\[\begin{split}\mathtt{XY}(\phi) = \begin{bmatrix} 1 & 0 & 0 & 0 \\ 0 & \cos{(\phi/2)} & i\sin{(\phi/2)} & 0 \\ 0 & i\sin{(\phi/2)} & \cos{(\phi/2)} & 0 \\ 0 & 0 & 0 & 1 \\ \end{bmatrix}.\end{split}\]

Parameters:

• target1 (QubitInput) – Target qubit 1 index.

• target2 (QubitInput) – Target qubit 2 index.

• angle (float | FreeParameterExpression) – angle in radians.

• control (QubitSetInput | None) – Control qubit(s). Default None.

• control_state (BasisStateInput | None) – Quantum state on which to control the operation. Must be a binary sequence of same length as number of qubits in control. Will be ignored if control is not present. May be represented as a string, list, or int. For example “0101”, [0, 1, 0, 1], 5 all represent controlling on qubits 0 and 2 being in the \|0⟩ state and qubits 1 and 3 being in the \|1⟩ state. Default “1” * len(control).

• power (float) – Integer or fractional power to raise the gate to. Negative powers will be split into an inverse, accompanied by the positive power. Default 1.

Return type:

TypeVar(SubroutineReturn, Iterable[Instruction], Instruction, ResultType, Iterable[ResultType])

Returns:

Instruction – XY instruction.

Examples

>>> circ = Circuit().xy(0, 1, 0.15)

y(*args, **kwargs) → SubroutineReturn

Pauli-Y gate.

Unitary matrix:

\[\begin{split}\mathtt{Y} = \begin{bmatrix} 0 & -i \\ i & 0 \end{bmatrix}.\end{split}\]

Parameters:

• target (QubitSetInput) – Target qubit(s)

• control (QubitSetInput | None) – Control qubit(s). Default None.

• control_state (BasisStateInput | None) – Quantum state on which to control the operation. Must be a binary sequence of same length as number of qubits in control. Will be ignored if control is not present. May be represented as a string, list, or int. For example “0101”, [0, 1, 0, 1], 5 all represent controlling on qubits 0 and 2 being in the \|0⟩ state and qubits 1 and 3 being in the \|1⟩ state. Default “1” * len(control).

• power (float) – Integer or fractional power to raise the gate to. Negative powers will be split into an inverse, accompanied by the positive power. Default 1.

Return type:

TypeVar(SubroutineReturn, Iterable[Instruction], Instruction, ResultType, Iterable[ResultType])

Returns:

Iterable[Instruction] – Iterable of Y instructions.

Examples

>>> circ = Circuit().y(0)
>>> circ = Circuit().y([0, 1, 2])

yy(*args, **kwargs) → SubroutineReturn

Ising YY coupling gate.

\[\begin{split}\mathtt{YY}(\phi) = \begin{bmatrix} \cos{(\phi/2)} & 0 & 0 & i \sin{(\phi/2)} \\ 0 & \cos{(\phi/2)} & -i \sin{(\phi/2)} & 0 \\ 0 & -i \sin{(\phi/2)} & \cos{(\phi/2)} & 0 \\ i \sin{(\phi/2)} & 0 & 0 & \cos{(\phi/2)} \end{bmatrix}.\end{split}\]

Parameters:

• target1 (QubitInput) – Target qubit 1 index.

• target2 (QubitInput) – Target qubit 2 index.

• angle (float | FreeParameterExpression) – angle in radians.

• control (QubitSetInput | None) – Control qubit(s). Default None.

• control_state (BasisStateInput | None) – Quantum state on which to control the operation. Must be a binary sequence of same length as number of qubits in control. Will be ignored if control is not present. May be represented as a string, list, or int. For example “0101”, [0, 1, 0, 1], 5 all represent controlling on qubits 0 and 2 being in the \|0⟩ state and qubits 1 and 3 being in the \|1⟩ state. Default “1” * len(control).

• power (float) – Integer or fractional power to raise the gate to. Negative powers will be split into an inverse, accompanied by the positive power. Default 1.

Return type:

TypeVar(SubroutineReturn, Iterable[Instruction], Instruction, ResultType, Iterable[ResultType])

Returns:

Instruction – YY instruction.

Examples

>>> circ = Circuit().yy(0, 1, 0.15)

z(*args, **kwargs) → SubroutineReturn

Pauli-Z gate.

\[\begin{split}\mathtt{Z} = \begin{bmatrix} 1 & 0 \\ 0 & -1 \end{bmatrix}.\end{split}\]

Parameters:

• target (QubitSetInput) – Target qubit(s)

• control (QubitSetInput | None) – Control qubit(s). Default None.

• control_state (BasisStateInput | None) – Quantum state on which to control the operation. Must be a binary sequence of same length as number of qubits in control. Will be ignored if control is not present. May be represented as a string, list, or int. For example “0101”, [0, 1, 0, 1], 5 all represent controlling on qubits 0 and 2 being in the \|0⟩ state and qubits 1 and 3 being in the \|1⟩ state. Default “1” * len(control).

• power (float) – Integer or fractional power to raise the gate to. Negative powers will be split into an inverse, accompanied by the positive power. Default 1.

Return type:

TypeVar(SubroutineReturn, Iterable[Instruction], Instruction, ResultType, Iterable[ResultType])

Returns:

Iterable[Instruction] – Iterable of Z instructions.

Examples

>>> circ = Circuit().z(0)
>>> circ = Circuit().z([0, 1, 2])

zz(*args, **kwargs) → SubroutineReturn

Ising ZZ coupling gate.

\[\begin{split}\mathtt{ZZ}(\phi) = \begin{bmatrix} e^{-i\phi/2} & 0 & 0 & 0 \\ 0 & e^{i\phi/2} & 0 & 0 \\ 0 & 0 & e^{i\phi/2} & 0 \\ 0 & 0 & 0 & e^{-i\phi/2} \end{bmatrix}.\end{split}\]

Parameters:

• target1 (QubitInput) – Target qubit 1 index.

• target2 (QubitInput) – Target qubit 2 index.

• angle (float | FreeParameterExpression) – angle in radians.

• control (QubitSetInput | None) – Control qubit(s). Default None.

• control_state (BasisStateInput | None) – Quantum state on which to control the operation. Must be a binary sequence of same length as number of qubits in control. Will be ignored if control is not present. May be represented as a string, list, or int. For example “0101”, [0, 1, 0, 1], 5 all represent controlling on qubits 0 and 2 being in the \|0⟩ state and qubits 1 and 3 being in the \|1⟩ state. Default “1” * len(control).

• power (float) – Integer or fractional power to raise the gate to. Negative powers will be split into an inverse, accompanied by the positive power. Default 1.

Return type:

TypeVar(SubroutineReturn, Iterable[Instruction], Instruction, ResultType, Iterable[ResultType])

Returns:

Instruction – ZZ instruction.

Examples

>>> circ = Circuit().zz(0, 1, 0.15)

braket.circuits.circuit.subroutine(register=False)

Subroutine is a function that returns instructions, result types, or circuits.

Parameters:

register (bool) – If True, adds this subroutine into the Circuit class. Default = False.

Return type:

Callable

Returns:

Callable – The subroutine function.

Examples

>>> @circuit.subroutine(register=True)
>>> def bell_circuit():
...     return Circuit().h(0).cnot(0, 1)
>>> circ = Circuit().bell_circuit()
>>> for instr in circ.instructions:
...     print(instr)
Instruction('operator': 'H', 'target': QubitSet(Qubit(0),))
Instruction('operator': 'H', 'target': QubitSet(Qubit(1),))