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
areInstruction
, iterable ofInstruction
,ResultType
, iterable ofResultType
, orSubroutineCallable
- Parameters
- 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 theCircuit
class. The attribute name is the name offunc
.- 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
qubit_count
¶ Get the qubit count for this circuit.
-
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
, returnsself
for chaining ability.- Parameters
result_type (ResultType) –
ResultType
to add intoself
.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 inresult_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 ofcircuit.result_types
only if it does not already exist incircuit.result_types
- Returns
Circuit – self
- Raises
TypeError – If both
target_mapping
andtarget
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
, returnsself
for chaining ability.- Parameters
instruction (Instruction) –
Instruction
to add intoself
.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 intarget
. 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 ininstruction.target
and the value is what the key will be changed to. Default = {}.
- Returns
Circuit – self
- Raises
TypeError – If both
target_mapping
andtarget
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 atarget_mapping
by zipping together a sortedcircuit.qubits
andtarget
. 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
andtarget
are supplied.
Note
Supplying
target
sortscircuit.qubits
to have deterministic behavior sincecircuit.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. Usetarget_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 / oradd_instruction()
and / oradd_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
- Returns
Instruction – CCNot instruction.
Examples
>>> circ = Circuit().ccnot(0, 1, 2)
-
cnot
(*args, **kwargs) → SubroutineReturn¶ Registers this function into the circuit class.
- Parameters
- Returns
Instruction – CNot instruction.
Examples
>>> circ = Circuit().cnot(0, 1)
-
cphaseshift
(*args, **kwargs) → SubroutineReturn¶ Registers this function into the circuit class.
- Parameters
- Returns
Instruction – CPhaseShift instruction.
Examples
>>> circ = Circuit().cphaseshift(0, 1, 0.15)
-
cphaseshift00
(*args, **kwargs) → SubroutineReturn¶ Registers this function into the circuit class.
- Parameters
- Returns
Instruction – CPhaseShift00 instruction.
Examples
>>> circ = Circuit().cphaseshift00(0, 1, 0.15)
-
cphaseshift01
(*args, **kwargs) → SubroutineReturn¶ Registers this function into the circuit class.
- Parameters
- Returns
Instruction – CPhaseShift01 instruction.
Examples
>>> circ = Circuit().cphaseshift01(0, 1, 0.15)
-
cphaseshift10
(*args, **kwargs) → SubroutineReturn¶ Registers this function into the circuit class.
- Parameters
- Returns
Instruction – CPhaseShift10 instruction.
Examples
>>> circ = Circuit().cphaseshift10(0, 1, 0.15)
-
cswap
(*args, **kwargs) → SubroutineReturn¶ Registers this function into the circuit class.
- Parameters
- Returns
Instruction – CSwap instruction.
Examples
>>> circ = Circuit().cswap(0, 1, 2)
-
cy
(*args, **kwargs) → SubroutineReturn¶ Registers this function into the circuit class.
- Parameters
- Returns
Instruction – CY instruction.
Examples
>>> circ = Circuit().cy(0, 1)
-
cz
(*args, **kwargs) → SubroutineReturn¶ Registers this function into the circuit class.
- Parameters
- 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
- 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
- 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
- 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 thetargets
, 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
- Returns
Instruction – XX instruction.
Examples
>>> circ = Circuit().xx(0, 1, 0.15)
-
xy
(*args, **kwargs) → SubroutineReturn¶ Registers this function into the circuit class.
- Parameters
- 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
- 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
- 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 theCircuit
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),))