braket.circuits.circuit module

class braket.circuits.circuit.Circuit(addable: Optional[AddableTypes] = None, *args, **kwargs)[source]

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 (AddableTypes) – The item(s) to add to self. Default = None.

  • *args – Variable length argument list. Supports any arguments that add() offers.

  • **kwargs – Arbitrary keyword arguments. Supports any keyword arguments that add() offers.

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: SubroutineCallable) → None[source]

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

Parameters

(Callable[.., Union[Instruction, Iterable[Instruction], ResultType, (func) – Iterable[ResultType]]): The function of the subroutine to add to the class.

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

Get the circuit depth.

Type

int

property instructions

Get an iterable of instructions in the circuit.

Type

Iterable[Instruction]

property result_types

Get a list of requested result types in the circuit.

Type

List[ResultType]

property basis_rotation_instructions

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.

Type

List[Instruction]

property moments

Get the moments for this circuit.

Type

Moments

property qubit_count

Get the qubit count for this circuit.

property qubits

Get a copy of the qubits for this circuit.

Type

QubitSet

add_result_type(result_type: braket.circuits.result_type.ResultType, target: Union[Qubit, int, Iterable[Union[Qubit, int]], None] = None, target_mapping: Dict[Union[Qubit, int], Union[Qubit, int]] = {})braket.circuits.circuit.Circuit[source]

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

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

  • target (int, Qubit, or iterable of int / Qubit, optional) – Target qubits for the result_type. Default = None.

  • target_mapping (dictionary[int or Qubit, int or Qubit], optional) – 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 = {}.

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 list of circuit.result_types only if it does not already exist in circuit.result_types

Returns

Circuit – self

Raises
  • TypeError – If both target_mapping and target are supplied.

  • ValueError – If the observable specified for a qubit is different from what is specified by the result types already added to the circuit. Only one observable is allowed for a qubit.

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: braket.circuits.instruction.Instruction, target: Union[Qubit, int, Iterable[Union[Qubit, int]], None] = None, target_mapping: Dict[Union[Qubit, int], Union[Qubit, int]] = {})braket.circuits.circuit.Circuit[source]

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

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

  • target (int, Qubit, or iterable of int / Qubit, optional) – Target qubits for the instruction. If a single qubit gate, an instruction is created for every index in target. Default = None.

  • target_mapping (dictionary[int or Qubit, int or Qubit], optional) – 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 = {}.

Returns

Circuit – self

Raises

TypeError – If both target_mapping and target are supplied.

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: braket.circuits.circuit.Circuit, target: Union[Qubit, int, Iterable[Union[Qubit, int]], None] = None, target_mapping: Dict[Union[Qubit, int], Union[Qubit, int]] = {})braket.circuits.circuit.Circuit[source]

Add a circuit to self, returns self for chaining ability.

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

  • target (int, Qubit, or iterable of int / Qubit, optional) – 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 (dictionary[int or Qubit, int or Qubit], optional) – 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 = {}.

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)
>>> print(circ.instructions[0])
Instruction('operator': 'H', 'target': QubitSet(Qubit(0),))
>>> print(circ.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})
>>> print(circ.instructions[0])
Instruction('operator': 'H', 'target': QubitSet(Qubit(10),))
>>> print(circ.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])
>>> print(circ.instructions[0])
Instruction('operator': 'H', 'target': QubitSet(Qubit(10),))
>>> print(circ.instructions[1])
Instruction('operator': 'CNOT', 'target': QubitSet(Qubit(10), Qubit(11)))
add(addable: AddableTypes, *args, **kwargs)braket.circuits.circuit.Circuit[source]

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.

  • *args – Variable length argument list.

  • **kwargs – Arbitrary keyword arguments.

Returns

Circuit – self

Raises

TypeError – If addable is an unsupported 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])
diagram(circuit_diagram_class=<class 'braket.circuits.ascii_circuit_diagram.AsciiCircuitDiagram'>) → str[source]

Get a diagram for the current circuit.

Parameters

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

Returns

str – An ASCII string circuit diagram.

to_ir() → braket.ir.jaqcd.program.Program[source]

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

Returns

(Program) – An AWS quantum circuit description program in JSON format.

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”

Returns

ResultType – state vector as a requested result type

Examples

>>> circ = Circuit().amplitude(state=["01", "10"])
ccnot(*args, **kwargs) → SubroutineReturn

Registers this function into the circuit class.

Parameters
  • control1 (Qubit or int) – Control qubit 1 index.

  • control2 (Qubit or int) – Control qubit 2 index.

  • target (Qubit or int) – Target qubit index.

Returns

Instruction – CCNot instruction.

Examples

>>> circ = Circuit().ccnot(0, 1, 2)
cnot(*args, **kwargs) → SubroutineReturn

Registers this function into the circuit class.

Parameters
  • control (Qubit or int) – Control qubit index.

  • target (Qubit or int) – Target qubit index.

Returns

Instruction – CNot instruction.

Examples

>>> circ = Circuit().cnot(0, 1)
cphaseshift(*args, **kwargs) → SubroutineReturn

Registers this function into the circuit class.

Parameters
  • control (Qubit or int) – Control qubit index.

  • target (Qubit or int) – Target qubit index.

  • angle (float) – Angle in radians.

Returns

Instruction – CPhaseShift instruction.

Examples

>>> circ = Circuit().cphaseshift(0, 1, 0.15)
cphaseshift00(*args, **kwargs) → SubroutineReturn

Registers this function into the circuit class.

Parameters
  • control (Qubit or int) – Control qubit index.

  • target (Qubit or int) – Target qubit index.

  • angle (float) – Angle in radians.

Returns

Instruction – CPhaseShift00 instruction.

Examples

>>> circ = Circuit().cphaseshift00(0, 1, 0.15)
cphaseshift01(*args, **kwargs) → SubroutineReturn

Registers this function into the circuit class.

Parameters
  • control (Qubit or int) – Control qubit index.

  • target (Qubit or int) – Target qubit index.

  • angle (float) – Angle in radians.

Returns

Instruction – CPhaseShift01 instruction.

Examples

>>> circ = Circuit().cphaseshift01(0, 1, 0.15)
cphaseshift10(*args, **kwargs) → SubroutineReturn

Registers this function into the circuit class.

Parameters
  • control (Qubit or int) – Control qubit index.

  • target (Qubit or int) – Target qubit index.

  • angle (float) – Angle in radians.

Returns

Instruction – CPhaseShift10 instruction.

Examples

>>> circ = Circuit().cphaseshift10(0, 1, 0.15)
cswap(*args, **kwargs) → SubroutineReturn

Registers this function into the circuit class.

Parameters
  • control (Qubit or int) – Control qubit index

  • target1 (Qubit or int) – Target qubit 1 index.

  • target2 (Qubit or int) – Target qubit 2 index.

Returns

Instruction – CSwap instruction.

Examples

>>> circ = Circuit().cswap(0, 1, 2)
cy(*args, **kwargs) → SubroutineReturn

Registers this function into the circuit class.

Parameters
  • control (Qubit or int) – Control qubit index.

  • target (Qubit or int) – Target qubit index.

Returns

Instruction – CY instruction.

Examples

>>> circ = Circuit().cy(0, 1)
cz(*args, **kwargs) → SubroutineReturn

Registers this function into the circuit class.

Parameters
  • control (Qubit or int) – Control qubit index.

  • target (Qubit or int) – Target qubit index.

Returns

Instruction – CZ instruction.

Examples

>>> circ = Circuit().cz(0, 1)
expectation(*args, **kwargs) → SubroutineReturn

Registers this function into the circuit class.

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

  • target (int, Qubit, or iterable of int / Qubit, optional) – 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

Returns

ResultType – expectation as a requested result type

Examples

>>> circ = Circuit().expectation(observable=Observable.Z(), target=0)
h(*args, **kwargs) → SubroutineReturn

Registers this function into the circuit class.

Parameters

target (Qubit, int, or iterable of Qubit / int) – Target qubit(s)

Returns

Iterable[Instruction]Iterable of H instructions.

Examples

>>> circ = Circuit().h(0)
>>> circ = Circuit().h([0, 1, 2])
i(*args, **kwargs) → SubroutineReturn

Registers this function into the circuit class.

Parameters

target (Qubit, int, or iterable of Qubit / int) – Target qubit(s)

Returns

Iterable[Instruction]Iterable of I instructions.

Examples

>>> circ = Circuit().i(0)
>>> circ = Circuit().i([0, 1, 2])
iswap(*args, **kwargs) → SubroutineReturn

Registers this function into the circuit class.

Parameters
  • target1 (Qubit or int) – Target qubit 1 index.

  • target2 (Qubit or int) – Target qubit 2 index.

Returns

Instruction – ISwap instruction.

Examples

>>> circ = Circuit().iswap(0, 1)
phaseshift(*args, **kwargs) → SubroutineReturn

Registers this function into the circuit class.

Parameters
  • target (Qubit or int) – Target qubit index.

  • angle (float) – Angle in radians.

Returns

Instruction – PhaseShift instruction.

Examples

>>> circ = Circuit().phaseshift(0, 0.15)
probability(*args, **kwargs) → SubroutineReturn

Registers this function into the circuit class.

Parameters

target (int, Qubit, or iterable of int / Qubit, optional) – Target qubits that the result type is requested for. Default is None, which means all qubits for the circuit.

Returns

ResultType – probability as a requested result type

Examples

>>> circ = Circuit().probability(target=[0, 1])
pswap(*args, **kwargs) → SubroutineReturn

Registers this function into the circuit class.

Parameters
  • target1 (Qubit or int) – Target qubit 1 index.

  • target2 (Qubit or int) – Target qubit 2 index.

Returns

Instruction – PSwap instruction.

Examples

>>> circ = Circuit().pswap(0, 1, 0.15)
rx(*args, **kwargs) → SubroutineReturn

Registers this function into the circuit class.

Parameters
  • target (Qubit or int) – Target qubit index.

  • angle (float) – Angle in radians.

Returns

Instruction – Rx instruction.

Examples

>>> circ = Circuit().rx(0, 0.15)
ry(*args, **kwargs) → SubroutineReturn

Registers this function into the circuit class.

Parameters
  • target (Qubit or int) – Target qubit index.

  • angle (float) – Angle in radians.

Returns

Instruction – Ry instruction.

Examples

>>> circ = Circuit().ry(0, 0.15)
rz(*args, **kwargs) → SubroutineReturn

Registers this function into the circuit class.

Parameters
  • target (Qubit or int) – Target qubit index.

  • angle (float) – Angle in radians.

Returns

Instruction – Rz instruction.

Examples

>>> circ = Circuit().rz(0, 0.15)
s(*args, **kwargs) → SubroutineReturn

Registers this function into the circuit class.

Parameters

target (Qubit, int, or iterable of Qubit / int) – Target qubit(s)

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 (int, Qubit, or iterable of int / Qubit, optional) – 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

Returns

ResultType – sample as a requested result type

Examples

>>> circ = Circuit().sample(observable=Observable.Z(), target=0)
si(*args, **kwargs) → SubroutineReturn

Registers this function into the circuit class.

Parameters

target (Qubit, int, or iterable of Qubit / int) – Target qubit(s)

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.

Returns

ResultType – state vector as a requested result type

Examples

>>> circ = Circuit().state_vector()
swap(*args, **kwargs) → SubroutineReturn

Registers this function into the circuit class.

Parameters
  • target1 (Qubit or int) – Target qubit 1 index.

  • target2 (Qubit or int) – Target qubit 2 index.

Returns

Instruction – Swap instruction.

Examples

>>> circ = Circuit().swap(0, 1)
t(*args, **kwargs) → SubroutineReturn

Registers this function into the circuit class.

Parameters

target (Qubit, int, or iterable of Qubit / int) – Target qubit(s)

Returns

Iterable[Instruction]Iterable of T instructions.

Examples

>>> circ = Circuit().t(0)
>>> circ = Circuit().t([0, 1, 2])
ti(*args, **kwargs) → SubroutineReturn

Registers this function into the circuit class.

Parameters

target (Qubit, int, or iterable of Qubit / int) – Target qubit(s)

Returns

Iterable[Instruction]Iterable of Ti instructions.

Examples

>>> circ = Circuit().ti(0)
>>> circ = Circuit().ti([0, 1, 2])
unitary(*args, **kwargs) → SubroutineReturn

Registers this function into the circuit class.

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.

Returns

Instruction – Unitary instruction.

Raises

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

Examples

>>> circ = Circuit().unitary(matrix=np.array([[0, 1],[1, 0]]), targets=[0])
v(*args, **kwargs) → SubroutineReturn

Registers this function into the circuit class.

Parameters

target (Qubit, int, or iterable of Qubit / int) – Target qubit(s)

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 (int, Qubit, or iterable of int / Qubit, optional) – 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

Returns

ResultType – variance as a requested result type

Examples

>>> circ = Circuit().variance(observable=Observable.Z(), target=0)
vi(*args, **kwargs) → SubroutineReturn

Registers this function into the circuit class.

Parameters

target (Qubit, int, or iterable of Qubit / int) – Target qubit(s)

Returns

Iterable[Instruction]Iterable of Vi instructions.

Examples

>>> circ = Circuit().vi(0)
>>> circ = Circuit().vi([0, 1, 2])
x(*args, **kwargs) → SubroutineReturn

Registers this function into the circuit class.

Parameters

target (Qubit, int, or iterable of Qubit / int) – Target qubit(s)

Returns

Iterable[Instruction]Iterable of X instructions.

Examples

>>> circ = Circuit().x(0)
>>> circ = Circuit().x([0, 1, 2])
xx(*args, **kwargs) → SubroutineReturn

Registers this function into the circuit class.

Parameters
  • target1 (Qubit or int) – Target qubit 1 index.

  • target2 (Qubit or int) – Target qubit 2 index.

  • angle (float) – Angle in radians.

Returns

Instruction – XX instruction.

Examples

>>> circ = Circuit().xx(0, 1, 0.15)
xy(*args, **kwargs) → SubroutineReturn

Registers this function into the circuit class.

Parameters
  • target1 (Qubit or int) – Target qubit 1 index.

  • target2 (Qubit or int) – Target qubit 2 index.

Returns

Instruction – XY instruction.

Examples

>>> circ = Circuit().xy(0, 1, 0.15)
y(*args, **kwargs) → SubroutineReturn

Registers this function into the circuit class.

Parameters

target (Qubit, int, or iterable of Qubit / int) – Target qubit(s)

Returns

Iterable[Instruction]Iterable of Y instructions.

Examples

>>> circ = Circuit().y(0)
>>> circ = Circuit().y([0, 1, 2])
yy(*args, **kwargs) → SubroutineReturn

Registers this function into the circuit class.

Parameters
  • target1 (Qubit or int) – Target qubit 1 index.

  • target2 (Qubit or int) – Target qubit 2 index.

  • angle (float) – Angle in radians.

Returns

Instruction – YY instruction.

Examples

>>> circ = Circuit().yy(0, 1, 0.15)
z(*args, **kwargs) → SubroutineReturn

Registers this function into the circuit class.

Parameters

target (Qubit, int, or iterable of Qubit / int) – Target qubit(s)

Returns

Iterable[Instruction]Iterable of Z instructions.

Examples

>>> circ = Circuit().z(0)
>>> circ = Circuit().z([0, 1, 2])
zz(*args, **kwargs) → SubroutineReturn

Registers this function into the circuit class.

Parameters
  • target1 (Qubit or int) – Target qubit 1 index.

  • target2 (Qubit or int) – Target qubit 2 index.

  • angle (float) – Angle in radians.

Returns

Instruction – ZZ instruction.

Examples

>>> circ = Circuit().zz(0, 1, 0.15)
braket.circuits.circuit.subroutine(register=False)[source]

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

Parameters

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

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