braket.circuits.gate module

class braket.circuits.gate.Gate(qubit_count: int | None, ascii_symbols: Sequence[str])

Bases: QuantumOperator

Class Gate represents a quantum gate that operates on N qubits. Gates are considered the building blocks of quantum circuits. This class is considered the gate definition containing the metadata that defines what a gate is and what it does.

Initializes a Gate.

Parameters:

• qubit_count (Optional[int]) – Number of qubits this gate interacts with.

• ascii_symbols (Sequence[str]) – ASCII string symbols for the gate. These are used when printing a diagram of circuits. Length must be the same as qubit_count, and index ordering is expected to correlate with target ordering on the instruction. For instance, if CNOT instruction has the control qubit on the first index and target qubit on the second index. Then ASCII symbols would have [“C”, “X”] to correlate a symbol with that index.

Raises:

ValueError – qubit_count is less than 1, ascii_symbols are None, or ascii_symbols length != qubit_count

adjoint() → list[Gate]

Returns a list of gates that implement the adjoint of this gate.

This is a list because some gates do not have an inverse defined by a single existing gate.

Returns:

list[Gate] – The gates comprising the adjoint of this gate.

to_ir(target: QubitSet, ir_type: IRType = IRType.JAQCD, serialization_properties: OpenQASMSerializationProperties | None = None, *, control: QubitSet | None = None, control_state: int | list[int] | str | BasisState | None = None, power: float = 1) → Any

Returns IR object of quantum operator and target

Parameters:

• target (QubitSet) – target qubit(s).

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

• serialization_properties (Optional[SerializationProperties]) – 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.

• control (Optional[QubitSet]) – Control qubit(s). Only supported for OpenQASM. Default None.

• control_state (Optional[BasisStateInput]) – 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.

Returns:

Any – IR object of the quantum operator and target

Raises:

• ValueError – If the supplied ir_type is not supported, or if the supplied serialization

• properties don't correspond to the ir_type. –

• ValueError – If gate modifiers are supplied with ir_type Jaqcd.

property ascii_symbols: tuple[str, ...]

Returns the ascii symbols for the quantum operator.

Type:

tuple[str, …]

classmethod register_gate(gate: type[Gate]) → None

Register a gate implementation by adding it into the Gate class.

Parameters:

gate (type[Gate]) – Gate class to register.

class CCNot

Bases: Gate

CCNOT gate or Toffoli gate.

Unitary matrix:

\[\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}\]

Initializes a Gate.

Parameters:

• qubit_count (Optional[int]) – Number of qubits this gate interacts with.

• ascii_symbols (Sequence[str]) – ASCII string symbols for the gate. These are used when printing a diagram of circuits. Length must be the same as qubit_count, and index ordering is expected to correlate with target ordering on the instruction. For instance, if CNOT instruction has the control qubit on the first index and target qubit on the second index. Then ASCII symbols would have [“C”, “X”] to correlate a symbol with that index.

Raises:

ValueError – qubit_count is less than 1, ascii_symbols are None, or ascii_symbols length != qubit_count

adjoint() → list[Gate]

Returns a list of gates that implement the adjoint of this gate.

This is a list because some gates do not have an inverse defined by a single existing gate.

Returns:

list[Gate] – The gates comprising the adjoint of this gate.

static ccnot(control1: QubitInput, control2: QubitInput, target: QubitInput, *, control: QubitSetInput | None = None, control_state: BasisStateInput | None = None, power: float = 1) → Instruction

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 (Optional[QubitSetInput]) – Control qubit(s), in addition to control1 and control2. Default None.

• control_state (Optional[BasisStateInput]) – 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.

Returns:

Instruction – CCNot instruction.

Examples

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

static fixed_qubit_count() → int

Returns the number of qubits this quantum operator acts on, if instances are guaranteed to act on the same number of qubits.

If different instances can act on a different number of qubits, this method returns NotImplemented.

Returns:

int – The number of qubits this quantum operator acts on.

to_matrix() → ndarray

Returns a matrix representation of the quantum operator.

Parameters:

• *args (Any) – Not Implemented.

• **kwargs (Any) – Not Implemented.

Raises:

NotImplementError – Not Implemented.

Returns:

np.ndarray – A matrix representation of the quantum operator

class CNot

Bases: Gate

Controlled NOT gate.

Unitary matrix:

\[\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}\]

Initializes a Gate.

Parameters:

• qubit_count (Optional[int]) – Number of qubits this gate interacts with.

• ascii_symbols (Sequence[str]) – ASCII string symbols for the gate. These are used when printing a diagram of circuits. Length must be the same as qubit_count, and index ordering is expected to correlate with target ordering on the instruction. For instance, if CNOT instruction has the control qubit on the first index and target qubit on the second index. Then ASCII symbols would have [“C”, “X”] to correlate a symbol with that index.

Raises:

ValueError – qubit_count is less than 1, ascii_symbols are None, or ascii_symbols length != qubit_count

adjoint() → list[Gate]

Returns a list of gates that implement the adjoint of this gate.

This is a list because some gates do not have an inverse defined by a single existing gate.

Returns:

list[Gate] – The gates comprising the adjoint of this gate.

static cnot(control: QubitSetInput, target: QubitInput, power: float = 1) → Instruction

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.

Returns:

Instruction – CNot instruction.

Examples

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

static fixed_qubit_count() → int

Returns the number of qubits this quantum operator acts on, if instances are guaranteed to act on the same number of qubits.

If different instances can act on a different number of qubits, this method returns NotImplemented.

Returns:

int – The number of qubits this quantum operator acts on.

to_matrix() → ndarray

Returns a matrix representation of the quantum operator.

Parameters:

• *args (Any) – Not Implemented.

• **kwargs (Any) – Not Implemented.

Raises:

NotImplementError – Not Implemented.

Returns:

np.ndarray – A matrix representation of the quantum operator

class CPhaseShift(angle: FreeParameterExpression | float)

Bases: AngledGate

Controlled phase shift gate.

Unitary matrix:

\[\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:

angle (Union[FreeParameterExpression, float]) – angle in radians.

Initializes an AngledGate.

Parameters:

• angle (Union[FreeParameterExpression, float]) – The angle of the gate in radians or expression representation.

• qubit_count (Optional[int]) – The number of qubits that this gate interacts with.

• ascii_symbols (Sequence[str]) – ASCII string symbols for the gate. These are used when printing a diagram of a circuit. The length must be the same as qubit_count, and index ordering is expected to correlate with the target ordering on the instruction. For instance, if a CNOT instruction has the control qubit on the first index and target qubit on the second index, the ASCII symbols should have ["C", "X"] to correlate a symbol with that index.

Raises:

ValueError – If the qubit_count is less than 1, ascii_symbols are None, or ascii_symbols length != qubit_count, or angle is None

bind_values(**kwargs) → AngledGate

Takes in parameters and attempts to assign them to values.

Returns:

AngledGate – A new Gate of the same type with the requested parameters bound.

Raises:

NotImplementedError – Subclasses should implement this function.

static cphaseshift(control: QubitSetInput, target: QubitInput, angle: FreeParameterExpression | float, power: float = 1) → Instruction

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 (Union[FreeParameterExpression, float]) – 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.

Returns:

Instruction – CPhaseShift instruction.

Examples

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

static fixed_qubit_count() → int

Returns the number of qubits this quantum operator acts on, if instances are guaranteed to act on the same number of qubits.

If different instances can act on a different number of qubits, this method returns NotImplemented.

Returns:

int – The number of qubits this quantum operator acts on.

to_matrix() → ndarray

Returns a matrix representation of the quantum operator.

Parameters:

• *args (Any) – Not Implemented.

• **kwargs (Any) – Not Implemented.

Raises:

NotImplementError – Not Implemented.

Returns:

np.ndarray – A matrix representation of the quantum operator

class CPhaseShift00(angle: FreeParameterExpression | float)

Bases: AngledGate

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

Unitary matrix:

\[\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:

angle (Union[FreeParameterExpression, float]) – angle in radians.

Initializes an AngledGate.

Parameters:

• angle (Union[FreeParameterExpression, float]) – The angle of the gate in radians or expression representation.

• qubit_count (Optional[int]) – The number of qubits that this gate interacts with.

• ascii_symbols (Sequence[str]) – ASCII string symbols for the gate. These are used when printing a diagram of a circuit. The length must be the same as qubit_count, and index ordering is expected to correlate with the target ordering on the instruction. For instance, if a CNOT instruction has the control qubit on the first index and target qubit on the second index, the ASCII symbols should have ["C", "X"] to correlate a symbol with that index.

Raises:

ValueError – If the qubit_count is less than 1, ascii_symbols are None, or ascii_symbols length != qubit_count, or angle is None

bind_values(**kwargs) → AngledGate

Takes in parameters and attempts to assign them to values.

Returns:

AngledGate – A new Gate of the same type with the requested parameters bound.

Raises:

NotImplementedError – Subclasses should implement this function.

static cphaseshift00(control: QubitSetInput, target: QubitInput, angle: FreeParameterExpression | float, power: float = 1) → Instruction

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 (Union[FreeParameterExpression, float]) – 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.

Returns:

Instruction – CPhaseShift00 instruction.

Examples

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

static fixed_qubit_count() → int

Returns the number of qubits this quantum operator acts on, if instances are guaranteed to act on the same number of qubits.

If different instances can act on a different number of qubits, this method returns NotImplemented.

Returns:

int – The number of qubits this quantum operator acts on.

to_matrix() → ndarray

Returns a matrix representation of the quantum operator.

Parameters:

• *args (Any) – Not Implemented.

• **kwargs (Any) – Not Implemented.

Raises:

NotImplementError – Not Implemented.

Returns:

np.ndarray – A matrix representation of the quantum operator

class CPhaseShift01(angle: FreeParameterExpression | float)

Bases: AngledGate

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

Unitary matrix:

\[\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:

angle (Union[FreeParameterExpression, float]) – angle in radians.

Initializes an AngledGate.

Parameters:

• angle (Union[FreeParameterExpression, float]) – The angle of the gate in radians or expression representation.

• qubit_count (Optional[int]) – The number of qubits that this gate interacts with.

• ascii_symbols (Sequence[str]) – ASCII string symbols for the gate. These are used when printing a diagram of a circuit. The length must be the same as qubit_count, and index ordering is expected to correlate with the target ordering on the instruction. For instance, if a CNOT instruction has the control qubit on the first index and target qubit on the second index, the ASCII symbols should have ["C", "X"] to correlate a symbol with that index.

Raises:

ValueError – If the qubit_count is less than 1, ascii_symbols are None, or ascii_symbols length != qubit_count, or angle is None

bind_values(**kwargs) → AngledGate

Takes in parameters and attempts to assign them to values.

Returns:

AngledGate – A new Gate of the same type with the requested parameters bound.

Raises:

NotImplementedError – Subclasses should implement this function.

static cphaseshift01(control: QubitSetInput, target: QubitInput, angle: FreeParameterExpression | float, power: float = 1) → Instruction

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 (Union[FreeParameterExpression, float]) – 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.

Returns:

Instruction – CPhaseShift01 instruction.

Examples

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

static fixed_qubit_count() → int

Returns the number of qubits this quantum operator acts on, if instances are guaranteed to act on the same number of qubits.

If different instances can act on a different number of qubits, this method returns NotImplemented.

Returns:

int – The number of qubits this quantum operator acts on.

to_matrix() → ndarray

Returns a matrix representation of the quantum operator.

Parameters:

• *args (Any) – Not Implemented.

• **kwargs (Any) – Not Implemented.

Raises:

NotImplementError – Not Implemented.

Returns:

np.ndarray – A matrix representation of the quantum operator

class CPhaseShift10(angle: FreeParameterExpression | float)

Bases: AngledGate

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

Unitary matrix:

\[\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:

angle (Union[FreeParameterExpression, float]) – angle in radians.

Initializes an AngledGate.

Parameters:

• angle (Union[FreeParameterExpression, float]) – The angle of the gate in radians or expression representation.

• qubit_count (Optional[int]) – The number of qubits that this gate interacts with.

• ascii_symbols (Sequence[str]) – ASCII string symbols for the gate. These are used when printing a diagram of a circuit. The length must be the same as qubit_count, and index ordering is expected to correlate with the target ordering on the instruction. For instance, if a CNOT instruction has the control qubit on the first index and target qubit on the second index, the ASCII symbols should have ["C", "X"] to correlate a symbol with that index.

Raises:

ValueError – If the qubit_count is less than 1, ascii_symbols are None, or ascii_symbols length != qubit_count, or angle is None

bind_values(**kwargs) → AngledGate

Takes in parameters and attempts to assign them to values.

Returns:

AngledGate – A new Gate of the same type with the requested parameters bound.

Raises:

NotImplementedError – Subclasses should implement this function.

static cphaseshift10(control: QubitSetInput, target: QubitInput, angle: FreeParameterExpression | float, power: float = 1) → Instruction

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 (Union[FreeParameterExpression, float]) – 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.

Returns:

Instruction – CPhaseShift10 instruction.

Examples

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

static fixed_qubit_count() → int

Returns the number of qubits this quantum operator acts on, if instances are guaranteed to act on the same number of qubits.

If different instances can act on a different number of qubits, this method returns NotImplemented.

Returns:

int – The number of qubits this quantum operator acts on.

to_matrix() → ndarray

Returns a matrix representation of the quantum operator.

Parameters:

• *args (Any) – Not Implemented.

• **kwargs (Any) – Not Implemented.

Raises:

NotImplementError – Not Implemented.

Returns:

np.ndarray – A matrix representation of the quantum operator

class CSwap

Bases: Gate

Controlled Swap gate.

Unitary matrix:

\[\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}\]

Initializes a Gate.

Parameters:

• qubit_count (Optional[int]) – Number of qubits this gate interacts with.

• ascii_symbols (Sequence[str]) – ASCII string symbols for the gate. These are used when printing a diagram of circuits. Length must be the same as qubit_count, and index ordering is expected to correlate with target ordering on the instruction. For instance, if CNOT instruction has the control qubit on the first index and target qubit on the second index. Then ASCII symbols would have [“C”, “X”] to correlate a symbol with that index.

Raises:

ValueError – qubit_count is less than 1, ascii_symbols are None, or ascii_symbols length != qubit_count

adjoint() → list[Gate]

Returns a list of gates that implement the adjoint of this gate.

This is a list because some gates do not have an inverse defined by a single existing gate.

Returns:

list[Gate] – The gates comprising the adjoint of this gate.

static cswap(control: QubitSetInput, target1: QubitInput, target2: QubitInput, power: float = 1) → Instruction

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.

Returns:

Instruction – CSwap instruction.

Examples

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

static fixed_qubit_count() → int

Returns the number of qubits this quantum operator acts on, if instances are guaranteed to act on the same number of qubits.

If different instances can act on a different number of qubits, this method returns NotImplemented.

Returns:

int – The number of qubits this quantum operator acts on.

to_matrix() → ndarray

Returns a matrix representation of the quantum operator.

Parameters:

• *args (Any) – Not Implemented.

• **kwargs (Any) – Not Implemented.

Raises:

NotImplementError – Not Implemented.

Returns:

np.ndarray – A matrix representation of the quantum operator

class CV

Bases: Gate

Controlled Sqrt of X gate.

Unitary matrix:

\[\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}\]

Initializes a Gate.

Parameters:

• qubit_count (Optional[int]) – Number of qubits this gate interacts with.

• ascii_symbols (Sequence[str]) – ASCII string symbols for the gate. These are used when printing a diagram of circuits. Length must be the same as qubit_count, and index ordering is expected to correlate with target ordering on the instruction. For instance, if CNOT instruction has the control qubit on the first index and target qubit on the second index. Then ASCII symbols would have [“C”, “X”] to correlate a symbol with that index.

Raises:

ValueError – qubit_count is less than 1, ascii_symbols are None, or ascii_symbols length != qubit_count

adjoint() → list[Gate]

Returns a list of gates that implement the adjoint of this gate.

This is a list because some gates do not have an inverse defined by a single existing gate.

Returns:

list[Gate] – The gates comprising the adjoint of this gate.

static cv(control: QubitSetInput, target: QubitInput, power: float = 1) → Instruction

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.

Returns:

Instruction – CV instruction.

Examples

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

static fixed_qubit_count() → int

Returns the number of qubits this quantum operator acts on, if instances are guaranteed to act on the same number of qubits.

If different instances can act on a different number of qubits, this method returns NotImplemented.

Returns:

int – The number of qubits this quantum operator acts on.

to_matrix() → ndarray

Returns a matrix representation of the quantum operator.

Parameters:

• *args (Any) – Not Implemented.

• **kwargs (Any) – Not Implemented.

Raises:

NotImplementError – Not Implemented.

Returns:

np.ndarray – A matrix representation of the quantum operator

class CY

Bases: Gate

Controlled Pauli-Y gate.

Unitary matrix:

\[\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}\]

Initializes a Gate.

Parameters:

• qubit_count (Optional[int]) – Number of qubits this gate interacts with.

• ascii_symbols (Sequence[str]) – ASCII string symbols for the gate. These are used when printing a diagram of circuits. Length must be the same as qubit_count, and index ordering is expected to correlate with target ordering on the instruction. For instance, if CNOT instruction has the control qubit on the first index and target qubit on the second index. Then ASCII symbols would have [“C”, “X”] to correlate a symbol with that index.

Raises:

ValueError – qubit_count is less than 1, ascii_symbols are None, or ascii_symbols length != qubit_count

adjoint() → list[Gate]

Returns a list of gates that implement the adjoint of this gate.

This is a list because some gates do not have an inverse defined by a single existing gate.

Returns:

list[Gate] – The gates comprising the adjoint of this gate.

static cy(control: QubitSetInput, target: QubitInput, power: float = 1) → Instruction

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.

Returns:

Instruction – CY instruction.

Examples

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

static fixed_qubit_count() → int

Returns the number of qubits this quantum operator acts on, if instances are guaranteed to act on the same number of qubits.

If different instances can act on a different number of qubits, this method returns NotImplemented.

Returns:

int – The number of qubits this quantum operator acts on.

to_matrix() → ndarray

Returns a matrix representation of the quantum operator.

Parameters:

• *args (Any) – Not Implemented.

• **kwargs (Any) – Not Implemented.

Raises:

NotImplementError – Not Implemented.

Returns:

np.ndarray – A matrix representation of the quantum operator

class CZ

Bases: Gate

Controlled Pauli-Z gate.

Unitary matrix:

\[\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}\]

Initializes a Gate.

Parameters:

• qubit_count (Optional[int]) – Number of qubits this gate interacts with.

• ascii_symbols (Sequence[str]) – ASCII string symbols for the gate. These are used when printing a diagram of circuits. Length must be the same as qubit_count, and index ordering is expected to correlate with target ordering on the instruction. For instance, if CNOT instruction has the control qubit on the first index and target qubit on the second index. Then ASCII symbols would have [“C”, “X”] to correlate a symbol with that index.

Raises:

ValueError – qubit_count is less than 1, ascii_symbols are None, or ascii_symbols length != qubit_count

adjoint() → list[Gate]

Returns a list of gates that implement the adjoint of this gate.

This is a list because some gates do not have an inverse defined by a single existing gate.

Returns:

list[Gate] – The gates comprising the adjoint of this gate.

static cz(control: QubitSetInput, target: QubitInput, power: float = 1) → Instruction

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.

Returns:

Instruction – CZ instruction.

Examples

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

static fixed_qubit_count() → int

Returns the number of qubits this quantum operator acts on, if instances are guaranteed to act on the same number of qubits.

If different instances can act on a different number of qubits, this method returns NotImplemented.

Returns:

int – The number of qubits this quantum operator acts on.

to_matrix() → ndarray

Returns a matrix representation of the quantum operator.

Parameters:

• *args (Any) – Not Implemented.

• **kwargs (Any) – Not Implemented.

Raises:

NotImplementError – Not Implemented.

Returns:

np.ndarray – A matrix representation of the quantum operator

class ECR

Bases: Gate

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

Unitary matrix:

\[\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}\]

Initializes a Gate.

Parameters:

• qubit_count (Optional[int]) – Number of qubits this gate interacts with.

• ascii_symbols (Sequence[str]) – ASCII string symbols for the gate. These are used when printing a diagram of circuits. Length must be the same as qubit_count, and index ordering is expected to correlate with target ordering on the instruction. For instance, if CNOT instruction has the control qubit on the first index and target qubit on the second index. Then ASCII symbols would have [“C”, “X”] to correlate a symbol with that index.

Raises:

ValueError – qubit_count is less than 1, ascii_symbols are None, or ascii_symbols length != qubit_count

adjoint() → list[Gate]

Returns a list of gates that implement the adjoint of this gate.

This is a list because some gates do not have an inverse defined by a single existing gate.

Returns:

list[Gate] – The gates comprising the adjoint of this gate.

static ecr(target1: QubitInput, target2: QubitInput, *, control: QubitSetInput | None = None, control_state: BasisStateInput | None = None, power: float = 1) → Instruction

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 (Optional[QubitSetInput]) – Control qubit(s). Default None.

• control_state (Optional[BasisStateInput]) – 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.

Returns:

Instruction – ECR instruction.

Examples

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

static fixed_qubit_count() → int

Returns the number of qubits this quantum operator acts on, if instances are guaranteed to act on the same number of qubits.

If different instances can act on a different number of qubits, this method returns NotImplemented.

Returns:

int – The number of qubits this quantum operator acts on.

to_matrix() → ndarray

Returns a matrix representation of the quantum operator.

Parameters:

• *args (Any) – Not Implemented.

• **kwargs (Any) – Not Implemented.

Raises:

NotImplementError – Not Implemented.

Returns:

np.ndarray – A matrix representation of the quantum operator

class GPhase(angle: FreeParameterExpression | float)

Bases: AngledGate

Global phase gate.

Unitary matrix:

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

Parameters:

angle (Union[FreeParameterExpression, float]) – angle in radians.

Raises:

ValueError – If angle is not present

Initializes an AngledGate.

Parameters:

• angle (Union[FreeParameterExpression, float]) – The angle of the gate in radians or expression representation.

• qubit_count (Optional[int]) – The number of qubits that this gate interacts with.

• ascii_symbols (Sequence[str]) – ASCII string symbols for the gate. These are used when printing a diagram of a circuit. The length must be the same as qubit_count, and index ordering is expected to correlate with the target ordering on the instruction. For instance, if a CNOT instruction has the control qubit on the first index and target qubit on the second index, the ASCII symbols should have ["C", "X"] to correlate a symbol with that index.

Raises:

ValueError – If the qubit_count is less than 1, ascii_symbols are None, or ascii_symbols length != qubit_count, or angle is None

adjoint() → list[Gate]

Returns the adjoint of this gate as a singleton list.

Returns:

list[Gate] – A list containing the gate with negated angle.

bind_values(**kwargs) → AngledGate

Takes in parameters and attempts to assign them to values.

Returns:

AngledGate – A new Gate of the same type with the requested parameters bound.

Raises:

NotImplementedError – Subclasses should implement this function.

static fixed_qubit_count() → int

Returns the number of qubits this quantum operator acts on, if instances are guaranteed to act on the same number of qubits.

If different instances can act on a different number of qubits, this method returns NotImplemented.

Returns:

int – The number of qubits this quantum operator acts on.

static gphase(angle: FreeParameterExpression | float, *, control: QubitSetInput | None = None, control_state: BasisStateInput | None = None, power: float = 1) → Instruction | Iterable[Instruction]

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 (Union[FreeParameterExpression, float]) – Phase in radians.

• control (Optional[QubitSetInput]) – Control qubit(s). Default None.

• control_state (Optional[BasisStateInput]) – 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.

Returns:

Instruction | Iterable[Instruction] – GPhase instruction.

Examples

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

to_matrix() → ndarray

Returns a matrix representation of the quantum operator.

Parameters:

• *args (Any) – Not Implemented.

• **kwargs (Any) – Not Implemented.

Raises:

NotImplementError – Not Implemented.

Returns:

np.ndarray – A matrix representation of the quantum operator

class GPi(angle: FreeParameterExpression | float)

Bases: AngledGate

IonQ GPi gate.

Unitary matrix:

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

Parameters:

angle (Union[FreeParameterExpression, float]) – angle in radians.

Initializes an AngledGate.

Parameters:

• angle (Union[FreeParameterExpression, float]) – The angle of the gate in radians or expression representation.

• qubit_count (Optional[int]) – The number of qubits that this gate interacts with.

• ascii_symbols (Sequence[str]) – ASCII string symbols for the gate. These are used when printing a diagram of a circuit. The length must be the same as qubit_count, and index ordering is expected to correlate with the target ordering on the instruction. For instance, if a CNOT instruction has the control qubit on the first index and target qubit on the second index, the ASCII symbols should have ["C", "X"] to correlate a symbol with that index.

Raises:

ValueError – If the qubit_count is less than 1, ascii_symbols are None, or ascii_symbols length != qubit_count, or angle is None

adjoint() → list[Gate]

Returns the adjoint of this gate as a singleton list.

Returns:

list[Gate] – A list containing the gate with negated angle.

bind_values(**kwargs) → GPi

Takes in parameters and attempts to assign them to values.

Returns:

AngledGate – A new Gate of the same type with the requested parameters bound.

Raises:

NotImplementedError – Subclasses should implement this function.

static fixed_qubit_count() → int

Returns the number of qubits this quantum operator acts on, if instances are guaranteed to act on the same number of qubits.

If different instances can act on a different number of qubits, this method returns NotImplemented.

Returns:

int – The number of qubits this quantum operator acts on.

static gpi(target: QubitSetInput, angle: FreeParameterExpression | float, *, control: QubitSetInput | None = None, control_state: BasisStateInput | None = None, power: float = 1) → Iterable[Instruction]

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 (Union[FreeParameterExpression, float]) – Angle in radians.

• control (Optional[QubitSetInput]) – Control qubit(s). Default None.

• control_state (Optional[BasisStateInput]) – 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.

Returns:

Iterable[Instruction] – GPi instruction.

Examples

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

to_matrix() → ndarray

Returns a matrix representation of the quantum operator.

Parameters:

• *args (Any) – Not Implemented.

• **kwargs (Any) – Not Implemented.

Raises:

NotImplementError – Not Implemented.

Returns:

np.ndarray – A matrix representation of the quantum operator

class GPi2(angle: FreeParameterExpression | float)

Bases: AngledGate

IonQ GPi2 gate.

Unitary matrix:

\[\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:

angle (Union[FreeParameterExpression, float]) – angle in radians.

Initializes an AngledGate.

Parameters:

• angle (Union[FreeParameterExpression, float]) – The angle of the gate in radians or expression representation.

• qubit_count (Optional[int]) – The number of qubits that this gate interacts with.

• ascii_symbols (Sequence[str]) – ASCII string symbols for the gate. These are used when printing a diagram of a circuit. The length must be the same as qubit_count, and index ordering is expected to correlate with the target ordering on the instruction. For instance, if a CNOT instruction has the control qubit on the first index and target qubit on the second index, the ASCII symbols should have ["C", "X"] to correlate a symbol with that index.

Raises:

ValueError – If the qubit_count is less than 1, ascii_symbols are None, or ascii_symbols length != qubit_count, or angle is None

adjoint() → list[Gate]

Returns the adjoint of this gate as a singleton list.

Returns:

list[Gate] – A list containing the gate with negated angle.

bind_values(**kwargs) → GPi2

Takes in parameters and attempts to assign them to values.

Returns:

AngledGate – A new Gate of the same type with the requested parameters bound.

Raises:

NotImplementedError – Subclasses should implement this function.

static fixed_qubit_count() → int

Returns the number of qubits this quantum operator acts on, if instances are guaranteed to act on the same number of qubits.

If different instances can act on a different number of qubits, this method returns NotImplemented.

Returns:

int – The number of qubits this quantum operator acts on.

static gpi2(target: QubitSetInput, angle: FreeParameterExpression | float, *, control: QubitSetInput | None = None, control_state: BasisStateInput | None = None, power: float = 1) → Iterable[Instruction]

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 (Union[FreeParameterExpression, float]) – Angle in radians.

• control (Optional[QubitSetInput]) – Control qubit(s). Default None.

• control_state (Optional[BasisStateInput]) – 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.

Returns:

Iterable[Instruction] – GPi2 instruction.

Examples

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

to_matrix() → ndarray

Returns a matrix representation of the quantum operator.

Parameters:

• *args (Any) – Not Implemented.

• **kwargs (Any) – Not Implemented.

Raises:

NotImplementError – Not Implemented.

Returns:

np.ndarray – A matrix representation of the quantum operator

class H

Bases: Gate

Hadamard gate.

Unitary matrix:

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

Initializes a Gate.

Parameters:

• qubit_count (Optional[int]) – Number of qubits this gate interacts with.

• ascii_symbols (Sequence[str]) – ASCII string symbols for the gate. These are used when printing a diagram of circuits. Length must be the same as qubit_count, and index ordering is expected to correlate with target ordering on the instruction. For instance, if CNOT instruction has the control qubit on the first index and target qubit on the second index. Then ASCII symbols would have [“C”, “X”] to correlate a symbol with that index.

Raises:

ValueError – qubit_count is less than 1, ascii_symbols are None, or ascii_symbols length != qubit_count

adjoint() → list[Gate]

Returns a list of gates that implement the adjoint of this gate.

This is a list because some gates do not have an inverse defined by a single existing gate.

Returns:

list[Gate] – The gates comprising the adjoint of this gate.

static fixed_qubit_count() → int

Returns the number of qubits this quantum operator acts on, if instances are guaranteed to act on the same number of qubits.

If different instances can act on a different number of qubits, this method returns NotImplemented.

Returns:

int – The number of qubits this quantum operator acts on.

static h(target: QubitSetInput, *, control: QubitSetInput | None = None, control_state: BasisStateInput | None = None, power: float = 1) → Iterable[Instruction]

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 (Optional[QubitSetInput]) – Control qubit(s). Default None.

• control_state (Optional[BasisStateInput]) – 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.

Returns:

Iterable[Instruction] – Iterable of H instructions.

Examples

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

to_matrix() → ndarray

Returns a matrix representation of the quantum operator.

Parameters:

• *args (Any) – Not Implemented.

• **kwargs (Any) – Not Implemented.

Raises:

NotImplementError – Not Implemented.

Returns:

np.ndarray – A matrix representation of the quantum operator

class I

Bases: Gate

Identity gate.

Unitary matrix:

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

Initializes a Gate.

Parameters:

• qubit_count (Optional[int]) – Number of qubits this gate interacts with.

• ascii_symbols (Sequence[str]) – ASCII string symbols for the gate. These are used when printing a diagram of circuits. Length must be the same as qubit_count, and index ordering is expected to correlate with target ordering on the instruction. For instance, if CNOT instruction has the control qubit on the first index and target qubit on the second index. Then ASCII symbols would have [“C”, “X”] to correlate a symbol with that index.

Raises:

ValueError – qubit_count is less than 1, ascii_symbols are None, or ascii_symbols length != qubit_count

adjoint() → list[Gate]

Returns a list of gates that implement the adjoint of this gate.

This is a list because some gates do not have an inverse defined by a single existing gate.

Returns:

list[Gate] – The gates comprising the adjoint of this gate.

static fixed_qubit_count() → int

Returns the number of qubits this quantum operator acts on, if instances are guaranteed to act on the same number of qubits.

If different instances can act on a different number of qubits, this method returns NotImplemented.

Returns:

int – The number of qubits this quantum operator acts on.

static i(target: QubitSetInput, *, control: QubitSetInput | None = None, control_state: BasisStateInput | None = None, power: float = 1) → Iterable[Instruction]

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 (Optional[QubitSetInput]) – Control qubit(s). Default None.

• control_state (Optional[BasisStateInput]) – 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.

Returns:

Iterable[Instruction] – Iterable of I instructions.

Examples

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

to_matrix() → ndarray

Returns a matrix representation of the quantum operator.

Parameters:

• *args (Any) – Not Implemented.

• **kwargs (Any) – Not Implemented.

Raises:

NotImplementError – Not Implemented.

Returns:

np.ndarray – A matrix representation of the quantum operator

class ISwap

Bases: Gate

ISwap gate.

Unitary matrix:

\[\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}\]

Initializes a Gate.

Parameters:

• qubit_count (Optional[int]) – Number of qubits this gate interacts with.

• ascii_symbols (Sequence[str]) – ASCII string symbols for the gate. These are used when printing a diagram of circuits. Length must be the same as qubit_count, and index ordering is expected to correlate with target ordering on the instruction. For instance, if CNOT instruction has the control qubit on the first index and target qubit on the second index. Then ASCII symbols would have [“C”, “X”] to correlate a symbol with that index.

Raises:

ValueError – qubit_count is less than 1, ascii_symbols are None, or ascii_symbols length != qubit_count

adjoint() → list[Gate]

Returns a list of gates that implement the adjoint of this gate.

This is a list because some gates do not have an inverse defined by a single existing gate.

Returns:

list[Gate] – The gates comprising the adjoint of this gate.

static fixed_qubit_count() → int

Returns the number of qubits this quantum operator acts on, if instances are guaranteed to act on the same number of qubits.

If different instances can act on a different number of qubits, this method returns NotImplemented.

Returns:

int – The number of qubits this quantum operator acts on.

static iswap(target1: QubitInput, target2: QubitInput, *, control: QubitSetInput | None = None, control_state: BasisStateInput | None = None, power: float = 1) → Instruction

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 (Optional[QubitSetInput]) – Control qubit(s). Default None.

• control_state (Optional[BasisStateInput]) – 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.

Returns:

Instruction – ISwap instruction.

Examples

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

to_matrix() → ndarray

Returns a matrix representation of the quantum operator.

Parameters:

• *args (Any) – Not Implemented.

• **kwargs (Any) – Not Implemented.

Raises:

NotImplementError – Not Implemented.

Returns:

np.ndarray – A matrix representation of the quantum operator

class MS(angle_1: FreeParameterExpression | float, angle_2: FreeParameterExpression | float, angle_3: FreeParameterExpression | float = 1.5707963267948966)

Bases: TripleAngledGate

IonQ Mølmer-Sørensen gate.

Unitary matrix:

\[\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:

• angle_1 (Union[FreeParameterExpression, float]) – angle in radians.

• angle_2 (Union[FreeParameterExpression, float]) – angle in radians.

• angle_3 (Union[FreeParameterExpression, float]) – angle in radians. Default value is angle_3=pi/2.

Inits a TripleAngledGate.

Parameters:

• angle_1 (Union[FreeParameterExpression, float]) – The first angle of the gate in radians or expression representation.

• angle_2 (Union[FreeParameterExpression, float]) – The second angle of the gate in radians or expression representation.

• angle_3 (Union[FreeParameterExpression, float]) – The third angle of the gate in radians or expression representation.

• qubit_count (Optional[int]) – The number of qubits that this gate interacts with.

• ascii_symbols (Sequence[str]) – ASCII string symbols for the gate. These are used when printing a diagram of a circuit. The length must be the same as qubit_count, and index ordering is expected to correlate with the target ordering on the instruction. For instance, if a CNOT instruction has the control qubit on the first index and target qubit on the second index, the ASCII symbols should have ["C", "X"] to correlate a symbol with that index.

Raises:

ValueError – If qubit_count is less than 1, ascii_symbols are None, or ascii_symbols length != qubit_count, or angle_1 or angle_2 or angle_3 is None

adjoint() → list[Gate]

Returns the adjoint of this gate as a singleton list.

Returns:

list[Gate] – A list containing the gate with negated angle.

bind_values(**kwargs) → MS

Takes in parameters and attempts to assign them to values.

Parameters:

**kwargs (FreeParameterExpression | str) – The parameters that are being assigned.

Returns:

AngledGate – A new Gate of the same type with the requested parameters bound.

Raises:

NotImplementedError – Subclasses should implement this function.

static fixed_qubit_count() → int

Returns the number of qubits this quantum operator acts on, if instances are guaranteed to act on the same number of qubits.

If different instances can act on a different number of qubits, this method returns NotImplemented.

Returns:

int – The number of qubits this quantum operator acts on.

static ms(target1: QubitInput, target2: QubitInput, angle_1: FreeParameterExpression | float, angle_2: FreeParameterExpression | float, angle_3: FreeParameterExpression | float = 1.5707963267948966, *, control: QubitSetInput | None = None, control_state: BasisStateInput | None = None, power: float = 1) → Iterable[Instruction]

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 (Union[FreeParameterExpression, float]) – angle in radians.

• angle_2 (Union[FreeParameterExpression, float]) – angle in radians.

• angle_3 (Union[FreeParameterExpression, float]) – angle in radians.

• control (Optional[QubitSetInput]) – Control qubit(s). Default None.

• control_state (Optional[BasisStateInput]) – 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.

Returns:

Iterable[Instruction] – MS instruction.

Examples

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

to_matrix() → ndarray

Returns a matrix representation of the quantum operator.

Parameters:

• *args (Any) – Not Implemented.

• **kwargs (Any) – Not Implemented.

Raises:

NotImplementError – Not Implemented.

Returns:

np.ndarray – A matrix representation of the quantum operator

class PRx(angle_1: FreeParameterExpression | float, angle_2: FreeParameterExpression | float)

Bases: DoubleAngledGate

Phase Rx gate.

Unitary matrix:

\[\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:

• angle_1 (Union[FreeParameterExpression, float]) – The first angle of the gate in radians or expression representation.

• angle_2 (Union[FreeParameterExpression, float]) – The second angle of the gate in radians or expression representation.

Inits a DoubleAngledGate.

Parameters:

• angle_1 (Union[FreeParameterExpression, float]) – The first angle of the gate in radians or expression representation.

• angle_2 (Union[FreeParameterExpression, float]) – The second angle of the gate in radians or expression representation.

• qubit_count (Optional[int]) – The number of qubits that this gate interacts with.

• ascii_symbols (Sequence[str]) – ASCII string symbols for the gate. These are used when printing a diagram of a circuit. The length must be the same as qubit_count, and index ordering is expected to correlate with the target ordering on the instruction. For instance, if a CNOT instruction has the control qubit on the first index and target qubit on the second index, the ASCII symbols should have ["C", "X"] to correlate a symbol with that index.

Raises:

ValueError – If qubit_count is less than 1, ascii_symbols are None, or ascii_symbols length != qubit_count, or angle_1 or angle_2 is None

adjoint() → list[Gate]

Returns the adjoint of this gate as a singleton list.

Returns:

list[Gate] – A list containing the gate with negated angle.

bind_values(**kwargs) → PRx

Takes in parameters and attempts to assign them to values.

Parameters:

**kwargs (FreeParameterExpression | str) – The parameters that are being assigned.

Returns:

AngledGate – A new Gate of the same type with the requested parameters bound.

Raises:

NotImplementedError – Subclasses should implement this function.

static fixed_qubit_count() → int

Returns the number of qubits this quantum operator acts on, if instances are guaranteed to act on the same number of qubits.

If different instances can act on a different number of qubits, this method returns NotImplemented.

Returns:

int – The number of qubits this quantum operator acts on.

static prx(target: QubitSetInput, angle_1: FreeParameterExpression | float, angle_2: FreeParameterExpression | float, *, control: QubitSetInput | None = None, control_state: BasisStateInput | None = None, power: float = 1) → Iterable[Instruction]

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 (Union[FreeParameterExpression, float]) – First angle in radians.

• angle_2 (Union[FreeParameterExpression, float]) – Second angle in radians.

• control (Optional[QubitSetInput]) – Control qubit(s). Default None.

• control_state (Optional[BasisStateInput]) – 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.

Returns:

Iterable[Instruction] – PhaseRx instruction.

Examples

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

to_matrix() → ndarray

Returns a matrix representation of this gate.

Returns:

np.ndarray – The matrix representation of this gate.

class PSwap(angle: FreeParameterExpression | float)

Bases: AngledGate

PSwap gate.

Unitary matrix:

\[\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:

angle (Union[FreeParameterExpression, float]) – angle in radians.

Initializes an AngledGate.

Parameters:

• angle (Union[FreeParameterExpression, float]) – The angle of the gate in radians or expression representation.

• qubit_count (Optional[int]) – The number of qubits that this gate interacts with.

• ascii_symbols (Sequence[str]) – ASCII string symbols for the gate. These are used when printing a diagram of a circuit. The length must be the same as qubit_count, and index ordering is expected to correlate with the target ordering on the instruction. For instance, if a CNOT instruction has the control qubit on the first index and target qubit on the second index, the ASCII symbols should have ["C", "X"] to correlate a symbol with that index.

Raises:

ValueError – If the qubit_count is less than 1, ascii_symbols are None, or ascii_symbols length != qubit_count, or angle is None

bind_values(**kwargs) → AngledGate

Takes in parameters and attempts to assign them to values.

Returns:

AngledGate – A new Gate of the same type with the requested parameters bound.

Raises:

NotImplementedError – Subclasses should implement this function.

static fixed_qubit_count() → int

Returns the number of qubits this quantum operator acts on, if instances are guaranteed to act on the same number of qubits.

If different instances can act on a different number of qubits, this method returns NotImplemented.

Returns:

int – The number of qubits this quantum operator acts on.

static pswap(target1: QubitInput, target2: QubitInput, angle: FreeParameterExpression | float, *, control: QubitSetInput | None = None, control_state: BasisStateInput | None = None, power: float = 1) → Instruction

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 (Union[FreeParameterExpression, float]) – angle in radians.

• control (Optional[QubitSetInput]) – Control qubit(s). Default None.

• control_state (Optional[BasisStateInput]) – 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.

Returns:

Instruction – PSwap instruction.

Examples

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

to_matrix() → ndarray

Returns a matrix representation of the quantum operator.

Parameters:

• *args (Any) – Not Implemented.

• **kwargs (Any) – Not Implemented.

Raises:

NotImplementError – Not Implemented.

Returns:

np.ndarray – A matrix representation of the quantum operator

class PhaseShift(angle: FreeParameterExpression | float)

Bases: AngledGate

Phase shift gate.

Unitary matrix:

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

Parameters:

angle (Union[FreeParameterExpression, float]) – angle in radians.

Initializes an AngledGate.

Parameters:

• angle (Union[FreeParameterExpression, float]) – The angle of the gate in radians or expression representation.

• qubit_count (Optional[int]) – The number of qubits that this gate interacts with.

• ascii_symbols (Sequence[str]) – ASCII string symbols for the gate. These are used when printing a diagram of a circuit. The length must be the same as qubit_count, and index ordering is expected to correlate with the target ordering on the instruction. For instance, if a CNOT instruction has the control qubit on the first index and target qubit on the second index, the ASCII symbols should have ["C", "X"] to correlate a symbol with that index.

Raises:

ValueError – If the qubit_count is less than 1, ascii_symbols are None, or ascii_symbols length != qubit_count, or angle is None

bind_values(**kwargs) → AngledGate

Takes in parameters and attempts to assign them to values.

Returns:

AngledGate – A new Gate of the same type with the requested parameters bound.

Raises:

NotImplementedError – Subclasses should implement this function.

static fixed_qubit_count() → int

Returns the number of qubits this quantum operator acts on, if instances are guaranteed to act on the same number of qubits.

If different instances can act on a different number of qubits, this method returns NotImplemented.

Returns:

int – The number of qubits this quantum operator acts on.

static phaseshift(target: QubitSetInput, angle: FreeParameterExpression | float, *, control: QubitSetInput | None = None, control_state: BasisStateInput | None = None, power: float = 1) → Iterable[Instruction]

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 (Union[FreeParameterExpression, float]) – angle in radians.

• control (Optional[QubitSetInput]) – Control qubit(s). Default None.

• control_state (Optional[BasisStateInput]) – 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.

Returns:

Iterable[Instruction] – PhaseShift instruction.

Examples

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

to_matrix() → ndarray

Returns a matrix representation of the quantum operator.

Parameters:

• *args (Any) – Not Implemented.

• **kwargs (Any) – Not Implemented.

Raises:

NotImplementError – Not Implemented.

Returns:

np.ndarray – A matrix representation of the quantum operator

class PulseGate(pulse_sequence: PulseSequence, qubit_count: int, display_name: str = 'PG')

Bases: Gate, Parameterizable

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

within circuits.

Parameters:

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

• qubit_count (int) – The number of qubits this pulse gate operates on.

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

Initializes a Gate.

Parameters:

• qubit_count (Optional[int]) – Number of qubits this gate interacts with.

• ascii_symbols (Sequence[str]) – ASCII string symbols for the gate. These are used when printing a diagram of circuits. Length must be the same as qubit_count, and index ordering is expected to correlate with target ordering on the instruction. For instance, if CNOT instruction has the control qubit on the first index and target qubit on the second index. Then ASCII symbols would have [“C”, “X”] to correlate a symbol with that index.

Raises:

ValueError – qubit_count is less than 1, ascii_symbols are None, or ascii_symbols length != qubit_count

bind_values(**kwargs) → PulseGate

Takes in parameters and returns an object with specified parameters replaced with their values.

Returns:

PulseGate – A copy of this gate with the requested parameters bound.

property parameters: list[FreeParameter]

Returns the list of FreeParameter s associated with the gate.

static pulse_gate(targets: QubitSet, pulse_sequence: PulseSequence, display_name: str = 'PG', *, control: QubitSetInput | None = None, control_state: BasisStateInput | None = None, power: float = 1) → Instruction

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 (Optional[QubitSetInput]) – Control qubit(s). Default None.

• control_state (Optional[BasisStateInput]) – 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.

Returns:

Instruction – Pulse gate instruction.

Examples

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

property pulse_sequence: PulseSequence

The underlying PulseSequence of this gate.

Type:

PulseSequence

to_matrix() → ndarray

Returns a matrix representation of the quantum operator.

Parameters:

• *args (Any) – Not Implemented.

• **kwargs (Any) – Not Implemented.

Raises:

NotImplementError – Not Implemented.

Returns:

np.ndarray – A matrix representation of the quantum operator

class Rx(angle: FreeParameterExpression | float)

Bases: AngledGate

X-axis rotation gate.

Unitary matrix:

\[\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:

angle (Union[FreeParameterExpression, float]) – angle in radians.

Initializes an AngledGate.

Parameters:

• angle (Union[FreeParameterExpression, float]) – The angle of the gate in radians or expression representation.

• qubit_count (Optional[int]) – The number of qubits that this gate interacts with.

• ascii_symbols (Sequence[str]) – ASCII string symbols for the gate. These are used when printing a diagram of a circuit. The length must be the same as qubit_count, and index ordering is expected to correlate with the target ordering on the instruction. For instance, if a CNOT instruction has the control qubit on the first index and target qubit on the second index, the ASCII symbols should have ["C", "X"] to correlate a symbol with that index.

Raises:

ValueError – If the qubit_count is less than 1, ascii_symbols are None, or ascii_symbols length != qubit_count, or angle is None

bind_values(**kwargs) → AngledGate

Takes in parameters and attempts to assign them to values.

Returns:

AngledGate – A new Gate of the same type with the requested parameters bound.

Raises:

NotImplementedError – Subclasses should implement this function.

static fixed_qubit_count() → int

Returns the number of qubits this quantum operator acts on, if instances are guaranteed to act on the same number of qubits.

If different instances can act on a different number of qubits, this method returns NotImplemented.

Returns:

int – The number of qubits this quantum operator acts on.

static rx(target: QubitSetInput, angle: FreeParameterExpression | float, *, control: QubitSetInput | None = None, control_state: BasisStateInput | None = None, power: float = 1) → Iterable[Instruction]

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 (Union[FreeParameterExpression, float]) – Angle in radians.

• control (Optional[QubitSetInput]) – Control qubit(s). Default None.

• control_state (Optional[BasisStateInput]) – 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.

Returns:

Iterable[Instruction] – Rx instruction.

Examples

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

to_matrix() → ndarray

Returns a matrix representation of this gate.

Returns:

np.ndarray – The matrix representation of this gate.

class Ry(angle: FreeParameterExpression | float)

Bases: AngledGate

Y-axis rotation gate.

Unitary matrix:

\[\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:

angle (Union[FreeParameterExpression, float]) – angle in radians.

Initializes an AngledGate.

Parameters:

• angle (Union[FreeParameterExpression, float]) – The angle of the gate in radians or expression representation.

• qubit_count (Optional[int]) – The number of qubits that this gate interacts with.

• ascii_symbols (Sequence[str]) – ASCII string symbols for the gate. These are used when printing a diagram of a circuit. The length must be the same as qubit_count, and index ordering is expected to correlate with the target ordering on the instruction. For instance, if a CNOT instruction has the control qubit on the first index and target qubit on the second index, the ASCII symbols should have ["C", "X"] to correlate a symbol with that index.

Raises:

ValueError – If the qubit_count is less than 1, ascii_symbols are None, or ascii_symbols length != qubit_count, or angle is None

bind_values(**kwargs) → AngledGate

Takes in parameters and attempts to assign them to values.

Returns:

AngledGate – A new Gate of the same type with the requested parameters bound.

Raises:

NotImplementedError – Subclasses should implement this function.

static fixed_qubit_count() → int

Returns the number of qubits this quantum operator acts on, if instances are guaranteed to act on the same number of qubits.

If different instances can act on a different number of qubits, this method returns NotImplemented.

Returns:

int – The number of qubits this quantum operator acts on.

static ry(target: QubitSetInput, angle: FreeParameterExpression | float, *, control: QubitSetInput | None = None, control_state: BasisStateInput | None = None, power: float = 1) → Iterable[Instruction]

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 (Union[FreeParameterExpression, float]) – Angle in radians.

• control (Optional[QubitSetInput]) – Control qubit(s). Default None.

• control_state (Optional[BasisStateInput]) – 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.

Returns:

Iterable[Instruction] – Rx instruction.

Examples

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

to_matrix() → ndarray

Returns a matrix representation of this gate.

Returns:

np.ndarray – The matrix representation of this gate.

class Rz(angle: FreeParameterExpression | float)

Bases: AngledGate

Z-axis rotation gate.

Unitary matrix:

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

Parameters:

angle (Union[FreeParameterExpression, float]) – angle in radians.

Initializes an AngledGate.

Parameters:

• angle (Union[FreeParameterExpression, float]) – The angle of the gate in radians or expression representation.

• qubit_count (Optional[int]) – The number of qubits that this gate interacts with.

• ascii_symbols (Sequence[str]) – ASCII string symbols for the gate. These are used when printing a diagram of a circuit. The length must be the same as qubit_count, and index ordering is expected to correlate with the target ordering on the instruction. For instance, if a CNOT instruction has the control qubit on the first index and target qubit on the second index, the ASCII symbols should have ["C", "X"] to correlate a symbol with that index.

Raises:

ValueError – If the qubit_count is less than 1, ascii_symbols are None, or ascii_symbols length != qubit_count, or angle is None

bind_values(**kwargs) → AngledGate

Takes in parameters and attempts to assign them to values.

Returns:

AngledGate – A new Gate of the same type with the requested parameters bound.

Raises:

NotImplementedError – Subclasses should implement this function.

static fixed_qubit_count() → int

Returns the number of qubits this quantum operator acts on, if instances are guaranteed to act on the same number of qubits.

If different instances can act on a different number of qubits, this method returns NotImplemented.

Returns:

int – The number of qubits this quantum operator acts on.

static rz(target: QubitSetInput, angle: FreeParameterExpression | float, *, control: QubitSetInput | None = None, control_state: BasisStateInput | None = None, power: float = 1) → Iterable[Instruction]

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 (Union[FreeParameterExpression, float]) – Angle in radians.

• control (Optional[QubitSetInput]) – Control qubit(s). Default None.

• control_state (Optional[BasisStateInput]) – 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.

Returns:

Iterable[Instruction] – Rx instruction.

Examples

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

to_matrix() → ndarray

Returns a matrix representation of the quantum operator.

Parameters:

• *args (Any) – Not Implemented.

• **kwargs (Any) – Not Implemented.

Raises:

NotImplementError – Not Implemented.

Returns:

np.ndarray – A matrix representation of the quantum operator

class S

Bases: Gate

S gate.

Unitary matrix:

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

Initializes a Gate.

Parameters:

• qubit_count (Optional[int]) – Number of qubits this gate interacts with.

• ascii_symbols (Sequence[str]) – ASCII string symbols for the gate. These are used when printing a diagram of circuits. Length must be the same as qubit_count, and index ordering is expected to correlate with target ordering on the instruction. For instance, if CNOT instruction has the control qubit on the first index and target qubit on the second index. Then ASCII symbols would have [“C”, “X”] to correlate a symbol with that index.

Raises:

ValueError – qubit_count is less than 1, ascii_symbols are None, or ascii_symbols length != qubit_count

adjoint() → list[Gate]

Returns a list of gates that implement the adjoint of this gate.

This is a list because some gates do not have an inverse defined by a single existing gate.

Returns:

list[Gate] – The gates comprising the adjoint of this gate.

static fixed_qubit_count() → int

Returns the number of qubits this quantum operator acts on, if instances are guaranteed to act on the same number of qubits.

If different instances can act on a different number of qubits, this method returns NotImplemented.

Returns:

int – The number of qubits this quantum operator acts on.

static s(target: QubitSetInput, *, control: QubitSetInput | None = None, control_state: BasisStateInput | None = None, power: float = 1) → Iterable[Instruction]

S gate.

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

Parameters:

• target (QubitSetInput) – Target qubit(s)

• control (Optional[QubitSetInput]) – Control qubit(s). Default None.

• control_state (Optional[BasisStateInput]) – 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.

Returns:

Iterable[Instruction] – Iterable of S instructions.

Examples

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

to_matrix() → ndarray

Returns a matrix representation of the quantum operator.

Parameters:

• *args (Any) – Not Implemented.

• **kwargs (Any) – Not Implemented.

Raises:

NotImplementError – Not Implemented.

Returns:

np.ndarray – A matrix representation of the quantum operator

class Si

Bases: Gate

Conjugate transpose of S gate.

Unitary matrix:

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

Initializes a Gate.

Parameters:

• qubit_count (Optional[int]) – Number of qubits this gate interacts with.

• ascii_symbols (Sequence[str]) – ASCII string symbols for the gate. These are used when printing a diagram of circuits. Length must be the same as qubit_count, and index ordering is expected to correlate with target ordering on the instruction. For instance, if CNOT instruction has the control qubit on the first index and target qubit on the second index. Then ASCII symbols would have [“C”, “X”] to correlate a symbol with that index.

Raises:

ValueError – qubit_count is less than 1, ascii_symbols are None, or ascii_symbols length != qubit_count

adjoint() → list[Gate]

Returns a list of gates that implement the adjoint of this gate.

This is a list because some gates do not have an inverse defined by a single existing gate.

Returns:

list[Gate] – The gates comprising the adjoint of this gate.

static fixed_qubit_count() → int

Returns the number of qubits this quantum operator acts on, if instances are guaranteed to act on the same number of qubits.

If different instances can act on a different number of qubits, this method returns NotImplemented.

Returns:

int – The number of qubits this quantum operator acts on.

static si(target: QubitSetInput, *, control: QubitSetInput | None = None, control_state: BasisStateInput | None = None, power: float = 1) → Iterable[Instruction]

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 (Optional[QubitSetInput]) – Control qubit(s). Default None.

• control_state (Optional[BasisStateInput]) – 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.

Returns:

Iterable[Instruction] – Iterable of Si instructions.

Examples

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

to_matrix() → ndarray

Returns a matrix representation of the quantum operator.

Parameters:

• *args (Any) – Not Implemented.

• **kwargs (Any) – Not Implemented.

Raises:

NotImplementError – Not Implemented.

Returns:

np.ndarray – A matrix representation of the quantum operator

class Swap

Bases: Gate

Swap gate.

Unitary matrix:

\[\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}\]

Initializes a Gate.

Parameters:

• qubit_count (Optional[int]) – Number of qubits this gate interacts with.

• ascii_symbols (Sequence[str]) – ASCII string symbols for the gate. These are used when printing a diagram of circuits. Length must be the same as qubit_count, and index ordering is expected to correlate with target ordering on the instruction. For instance, if CNOT instruction has the control qubit on the first index and target qubit on the second index. Then ASCII symbols would have [“C”, “X”] to correlate a symbol with that index.

Raises:

ValueError – qubit_count is less than 1, ascii_symbols are None, or ascii_symbols length != qubit_count

adjoint() → list[Gate]

Returns a list of gates that implement the adjoint of this gate.

This is a list because some gates do not have an inverse defined by a single existing gate.

Returns:

list[Gate] – The gates comprising the adjoint of this gate.

static fixed_qubit_count() → int

Returns the number of qubits this quantum operator acts on, if instances are guaranteed to act on the same number of qubits.

If different instances can act on a different number of qubits, this method returns NotImplemented.

Returns:

int – The number of qubits this quantum operator acts on.

static swap(target1: QubitInput, target2: QubitInput, *, control: QubitSetInput | None = None, control_state: BasisStateInput | None = None, power: float = 1) → Instruction

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 (Optional[QubitSetInput]) – Control qubit(s). Default None.

• control_state (Optional[BasisStateInput]) – 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.

Returns:

Instruction – Swap instruction.

Examples

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

to_matrix() → ndarray

Returns a matrix representation of the quantum operator.

Parameters:

• *args (Any) – Not Implemented.

• **kwargs (Any) – Not Implemented.

Raises:

NotImplementError – Not Implemented.

Returns:

np.ndarray – A matrix representation of the quantum operator

class T

Bases: Gate

T gate.

Unitary matrix:

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

Initializes a Gate.

Parameters:

• qubit_count (Optional[int]) – Number of qubits this gate interacts with.

• ascii_symbols (Sequence[str]) – ASCII string symbols for the gate. These are used when printing a diagram of circuits. Length must be the same as qubit_count, and index ordering is expected to correlate with target ordering on the instruction. For instance, if CNOT instruction has the control qubit on the first index and target qubit on the second index. Then ASCII symbols would have [“C”, “X”] to correlate a symbol with that index.

Raises:

ValueError – qubit_count is less than 1, ascii_symbols are None, or ascii_symbols length != qubit_count

adjoint() → list[Gate]

Returns a list of gates that implement the adjoint of this gate.

This is a list because some gates do not have an inverse defined by a single existing gate.

Returns:

list[Gate] – The gates comprising the adjoint of this gate.

static fixed_qubit_count() → int

Returns the number of qubits this quantum operator acts on, if instances are guaranteed to act on the same number of qubits.

If different instances can act on a different number of qubits, this method returns NotImplemented.

Returns:

int – The number of qubits this quantum operator acts on.

static t(target: QubitSetInput, *, control: QubitSetInput | None = None, control_state: BasisStateInput | None = None, power: float = 1) → Iterable[Instruction]

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 (Optional[QubitSetInput]) – Control qubit(s). Default None.

• control_state (Optional[BasisStateInput]) – 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.

Returns:

Iterable[Instruction] – Iterable of T instructions.

Examples

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

to_matrix() → ndarray

Returns a matrix representation of the quantum operator.

Parameters:

• *args (Any) – Not Implemented.

• **kwargs (Any) – Not Implemented.

Raises:

NotImplementError – Not Implemented.

Returns:

np.ndarray – A matrix representation of the quantum operator

class Ti

Bases: Gate

Conjugate transpose of T gate.

Unitary matrix:

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

Initializes a Gate.

Parameters:

• qubit_count (Optional[int]) – Number of qubits this gate interacts with.

• ascii_symbols (Sequence[str]) – ASCII string symbols for the gate. These are used when printing a diagram of circuits. Length must be the same as qubit_count, and index ordering is expected to correlate with target ordering on the instruction. For instance, if CNOT instruction has the control qubit on the first index and target qubit on the second index. Then ASCII symbols would have [“C”, “X”] to correlate a symbol with that index.

Raises:

ValueError – qubit_count is less than 1, ascii_symbols are None, or ascii_symbols length != qubit_count

adjoint() → list[Gate]

Returns a list of gates that implement the adjoint of this gate.

This is a list because some gates do not have an inverse defined by a single existing gate.

Returns:

list[Gate] – The gates comprising the adjoint of this gate.

static fixed_qubit_count() → int

Returns the number of qubits this quantum operator acts on, if instances are guaranteed to act on the same number of qubits.

If different instances can act on a different number of qubits, this method returns NotImplemented.

Returns:

int – The number of qubits this quantum operator acts on.

static ti(target: QubitSetInput, *, control: QubitSetInput | None = None, control_state: BasisStateInput | None = None, power: float = 1) → Iterable[Instruction]

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 (Optional[QubitSetInput]) – Control qubit(s). Default None.

• control_state (Optional[BasisStateInput]) – 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.

Returns:

Iterable[Instruction] – Iterable of Ti instructions.

Examples

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

to_matrix() → ndarray

Returns a matrix representation of the quantum operator.

Parameters:

• *args (Any) – Not Implemented.

• **kwargs (Any) – Not Implemented.

Raises:

NotImplementError – Not Implemented.

Returns:

np.ndarray – A matrix representation of the quantum operator

class U(angle_1: FreeParameterExpression | float, angle_2: FreeParameterExpression | float, angle_3: FreeParameterExpression | float)

Bases: TripleAngledGate

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:

• angle_1 (Union[FreeParameterExpression, float]) – theta angle in radians.

• angle_2 (Union[FreeParameterExpression, float]) – phi angle in radians.

• angle_3 (Union[FreeParameterExpression, float]) – lambda angle in radians.

Inits a TripleAngledGate.

Parameters:

• angle_1 (Union[FreeParameterExpression, float]) – The first angle of the gate in radians or expression representation.

• angle_2 (Union[FreeParameterExpression, float]) – The second angle of the gate in radians or expression representation.

• angle_3 (Union[FreeParameterExpression, float]) – The third angle of the gate in radians or expression representation.

• qubit_count (Optional[int]) – The number of qubits that this gate interacts with.

• ascii_symbols (Sequence[str]) – ASCII string symbols for the gate. These are used when printing a diagram of a circuit. The length must be the same as qubit_count, and index ordering is expected to correlate with the target ordering on the instruction. For instance, if a CNOT instruction has the control qubit on the first index and target qubit on the second index, the ASCII symbols should have ["C", "X"] to correlate a symbol with that index.

Raises:

ValueError – If qubit_count is less than 1, ascii_symbols are None, or ascii_symbols length != qubit_count, or angle_1 or angle_2 or angle_3 is None

adjoint() → list[Gate]

Returns the adjoint of this gate as a singleton list.

Returns:

list[Gate] – A list containing the gate with negated angle.

bind_values(**kwargs) → TripleAngledGate

Takes in parameters and attempts to assign them to values.

Parameters:

**kwargs (FreeParameterExpression | str) – The parameters that are being assigned.

Returns:

AngledGate – A new Gate of the same type with the requested parameters bound.

Raises:

NotImplementedError – Subclasses should implement this function.

static fixed_qubit_count() → int

Returns the number of qubits this quantum operator acts on, if instances are guaranteed to act on the same number of qubits.

If different instances can act on a different number of qubits, this method returns NotImplemented.

Returns:

int – The number of qubits this quantum operator acts on.

to_matrix() → ndarray

Returns a matrix representation of this gate.

Returns:

np.ndarray – The matrix representation of this gate.

static u(target: QubitSetInput, angle_1: FreeParameterExpression | float, angle_2: FreeParameterExpression | float, angle_3: FreeParameterExpression | float, *, control: QubitSetInput | None = None, control_state: BasisStateInput | None = None, power: float = 1) → Iterable[Instruction]

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 (Union[FreeParameterExpression, float]) – theta angle in radians.

• angle_2 (Union[FreeParameterExpression, float]) – phi angle in radians.

• angle_3 (Union[FreeParameterExpression, float]) – lambda angle in radians.

• control (Optional[QubitSetInput]) – Control qubit(s). Default None.

• control_state (Optional[BasisStateInput]) – 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.

Returns:

Iterable[Instruction] – U instruction.

Examples

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

class Unitary(matrix: ndarray, display_name: str = 'U')

Bases: Gate

Arbitrary unitary gate.

Parameters:

• matrix (numpy.ndarray) – Unitary matrix which defines the gate.

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

Raises:

ValueError – If matrix is not a two-dimensional square matrix, or has a dimension length that is not a positive power of 2, or is not unitary.

Initializes a Gate.

Parameters:

• qubit_count (Optional[int]) – Number of qubits this gate interacts with.

• ascii_symbols (Sequence[str]) – ASCII string symbols for the gate. These are used when printing a diagram of circuits. Length must be the same as qubit_count, and index ordering is expected to correlate with target ordering on the instruction. For instance, if CNOT instruction has the control qubit on the first index and target qubit on the second index. Then ASCII symbols would have [“C”, “X”] to correlate a symbol with that index.

Raises:

ValueError – qubit_count is less than 1, ascii_symbols are None, or ascii_symbols length != qubit_count

adjoint() → list[Gate]

Returns a list of gates that implement the adjoint of this gate.

This is a list because some gates do not have an inverse defined by a single existing gate.

Returns:

list[Gate] – The gates comprising the adjoint of this gate.

to_matrix() → ndarray

Returns a matrix representation of the quantum operator.

Parameters:

• *args (Any) – Not Implemented.

• **kwargs (Any) – Not Implemented.

Raises:

NotImplementError – Not Implemented.

Returns:

np.ndarray – A matrix representation of the quantum operator

static unitary(targets: QubitSet, matrix: ndarray, display_name: str = 'U') → Instruction

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.

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

class V

Bases: Gate

Square root of X gate (V gate).

Unitary matrix:

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

Initializes a Gate.

Parameters:

• qubit_count (Optional[int]) – Number of qubits this gate interacts with.

• ascii_symbols (Sequence[str]) – ASCII string symbols for the gate. These are used when printing a diagram of circuits. Length must be the same as qubit_count, and index ordering is expected to correlate with target ordering on the instruction. For instance, if CNOT instruction has the control qubit on the first index and target qubit on the second index. Then ASCII symbols would have [“C”, “X”] to correlate a symbol with that index.

Raises:

ValueError – qubit_count is less than 1, ascii_symbols are None, or ascii_symbols length != qubit_count

adjoint() → list[Gate]

Returns a list of gates that implement the adjoint of this gate.

This is a list because some gates do not have an inverse defined by a single existing gate.

Returns:

list[Gate] – The gates comprising the adjoint of this gate.

static fixed_qubit_count() → int

Returns the number of qubits this quantum operator acts on, if instances are guaranteed to act on the same number of qubits.

If different instances can act on a different number of qubits, this method returns NotImplemented.

Returns:

int – The number of qubits this quantum operator acts on.

to_matrix() → ndarray

Returns a matrix representation of the quantum operator.

Parameters:

• *args (Any) – Not Implemented.

• **kwargs (Any) – Not Implemented.

Raises:

NotImplementError – Not Implemented.

Returns:

np.ndarray – A matrix representation of the quantum operator

static v(target: QubitSetInput, *, control: QubitSetInput | None = None, control_state: BasisStateInput | None = None, power: float = 1) → Iterable[Instruction]

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 (Optional[QubitSetInput]) – Control qubit(s). Default None.

• control_state (Optional[BasisStateInput]) – 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.

Returns:

Iterable[Instruction] – Iterable of V instructions.

Examples

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

class Vi

Bases: Gate

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

Unitary matrix:

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

Initializes a Gate.

Parameters:

• qubit_count (Optional[int]) – Number of qubits this gate interacts with.

• ascii_symbols (Sequence[str]) – ASCII string symbols for the gate. These are used when printing a diagram of circuits. Length must be the same as qubit_count, and index ordering is expected to correlate with target ordering on the instruction. For instance, if CNOT instruction has the control qubit on the first index and target qubit on the second index. Then ASCII symbols would have [“C”, “X”] to correlate a symbol with that index.

Raises:

ValueError – qubit_count is less than 1, ascii_symbols are None, or ascii_symbols length != qubit_count

adjoint() → list[Gate]

Returns a list of gates that implement the adjoint of this gate.

This is a list because some gates do not have an inverse defined by a single existing gate.

Returns:

list[Gate] – The gates comprising the adjoint of this gate.

static fixed_qubit_count() → int

Returns the number of qubits this quantum operator acts on, if instances are guaranteed to act on the same number of qubits.

If different instances can act on a different number of qubits, this method returns NotImplemented.

Returns:

int – The number of qubits this quantum operator acts on.

to_matrix() → ndarray

Returns a matrix representation of the quantum operator.

Parameters:

• *args (Any) – Not Implemented.

• **kwargs (Any) – Not Implemented.

Raises:

NotImplementError – Not Implemented.

Returns:

np.ndarray – A matrix representation of the quantum operator

static vi(target: QubitSetInput, *, control: QubitSetInput | None = None, control_state: BasisStateInput | None = None, power: float = 1) → Iterable[Instruction]

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 (Optional[QubitSetInput]) – Control qubit(s). Default None.

• control_state (Optional[BasisStateInput]) – 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.

Returns:

Iterable[Instruction] – Iterable of Vi instructions.

Examples

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

class X

Bases: Gate

Pauli-X gate.

Unitary matrix:

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

Initializes a Gate.

Parameters:

• qubit_count (Optional[int]) – Number of qubits this gate interacts with.

• ascii_symbols (Sequence[str]) – ASCII string symbols for the gate. These are used when printing a diagram of circuits. Length must be the same as qubit_count, and index ordering is expected to correlate with target ordering on the instruction. For instance, if CNOT instruction has the control qubit on the first index and target qubit on the second index. Then ASCII symbols would have [“C”, “X”] to correlate a symbol with that index.

Raises:

ValueError – qubit_count is less than 1, ascii_symbols are None, or ascii_symbols length != qubit_count

adjoint() → list[Gate]

Returns a list of gates that implement the adjoint of this gate.

This is a list because some gates do not have an inverse defined by a single existing gate.

Returns:

list[Gate] – The gates comprising the adjoint of this gate.

static fixed_qubit_count() → int

Returns the number of qubits this quantum operator acts on, if instances are guaranteed to act on the same number of qubits.

If different instances can act on a different number of qubits, this method returns NotImplemented.

Returns:

int – The number of qubits this quantum operator acts on.

to_matrix() → ndarray

Returns a matrix representation of the quantum operator.

Parameters:

• *args (Any) – Not Implemented.

• **kwargs (Any) – Not Implemented.

Raises:

NotImplementError – Not Implemented.

Returns:

np.ndarray – A matrix representation of the quantum operator

static x(target: QubitSetInput, *, control: QubitSetInput | None = None, control_state: BasisStateInput | None = None, power: float = 1) → Iterable[Instruction]

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 (Optional[QubitSetInput]) – Control qubit(s). Default None.

• control_state (Optional[BasisStateInput]) – 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.

Returns:

Iterable[Instruction] – Iterable of X instructions.

Examples

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

class XX(angle: FreeParameterExpression | float)

Bases: AngledGate

Ising XX coupling gate.

Unitary matrix:

\[\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}\]

Reference: https://arxiv.org/abs/1707.06356

Parameters:

angle (Union[FreeParameterExpression, float]) – angle in radians.

Initializes an AngledGate.

Parameters:

• angle (Union[FreeParameterExpression, float]) – The angle of the gate in radians or expression representation.

• qubit_count (Optional[int]) – The number of qubits that this gate interacts with.

• ascii_symbols (Sequence[str]) – ASCII string symbols for the gate. These are used when printing a diagram of a circuit. The length must be the same as qubit_count, and index ordering is expected to correlate with the target ordering on the instruction. For instance, if a CNOT instruction has the control qubit on the first index and target qubit on the second index, the ASCII symbols should have ["C", "X"] to correlate a symbol with that index.

Raises:

ValueError – If the qubit_count is less than 1, ascii_symbols are None, or ascii_symbols length != qubit_count, or angle is None

bind_values(**kwargs) → AngledGate

Takes in parameters and attempts to assign them to values.

Returns:

AngledGate – A new Gate of the same type with the requested parameters bound.

Raises:

NotImplementedError – Subclasses should implement this function.

static fixed_qubit_count() → int

Returns the number of qubits this quantum operator acts on, if instances are guaranteed to act on the same number of qubits.

If different instances can act on a different number of qubits, this method returns NotImplemented.

Returns:

int – The number of qubits this quantum operator acts on.

to_matrix() → ndarray

Returns a matrix representation of this gate.

Returns:

np.ndarray – The matrix representation of this gate.

static xx(target1: QubitInput, target2: QubitInput, angle: FreeParameterExpression | float, *, control: QubitSetInput | None = None, control_state: BasisStateInput | None = None, power: float = 1) → Instruction

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 (Union[FreeParameterExpression, float]) – angle in radians.

• control (Optional[QubitSetInput]) – Control qubit(s). Default None.

• control_state (Optional[BasisStateInput]) – 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.

Returns:

Instruction – XX instruction.

Examples

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

class XY(angle: FreeParameterExpression | float)

Bases: AngledGate

XY gate.

Unitary matrix:

\[\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}\]

Reference: https://arxiv.org/abs/1912.04424v1

Parameters:

angle (Union[FreeParameterExpression, float]) – angle in radians.

Initializes an AngledGate.

Parameters:

• angle (Union[FreeParameterExpression, float]) – The angle of the gate in radians or expression representation.

• qubit_count (Optional[int]) – The number of qubits that this gate interacts with.

• ascii_symbols (Sequence[str]) – ASCII string symbols for the gate. These are used when printing a diagram of a circuit. The length must be the same as qubit_count, and index ordering is expected to correlate with the target ordering on the instruction. For instance, if a CNOT instruction has the control qubit on the first index and target qubit on the second index, the ASCII symbols should have ["C", "X"] to correlate a symbol with that index.

Raises:

ValueError – If the qubit_count is less than 1, ascii_symbols are None, or ascii_symbols length != qubit_count, or angle is None

bind_values(**kwargs) → AngledGate

Takes in parameters and attempts to assign them to values.

Returns:

AngledGate – A new Gate of the same type with the requested parameters bound.

Raises:

NotImplementedError – Subclasses should implement this function.

static fixed_qubit_count() → int

Returns the number of qubits this quantum operator acts on, if instances are guaranteed to act on the same number of qubits.

If different instances can act on a different number of qubits, this method returns NotImplemented.

Returns:

int – The number of qubits this quantum operator acts on.

to_matrix() → ndarray

Returns a matrix representation of this gate.

Returns:

np.ndarray – The matrix representation of this gate.

static xy(target1: QubitInput, target2: QubitInput, angle: FreeParameterExpression | float, *, control: QubitSetInput | None = None, control_state: BasisStateInput | None = None, power: float = 1) → Instruction

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 (Union[FreeParameterExpression, float]) – angle in radians.

• control (Optional[QubitSetInput]) – Control qubit(s). Default None.

• control_state (Optional[BasisStateInput]) – 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.

Returns:

Instruction – XY instruction.

Examples

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

class Y

Bases: Gate

Pauli-Y gate.

Unitary matrix:

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

Initializes a Gate.

Parameters:

• qubit_count (Optional[int]) – Number of qubits this gate interacts with.

• ascii_symbols (Sequence[str]) – ASCII string symbols for the gate. These are used when printing a diagram of circuits. Length must be the same as qubit_count, and index ordering is expected to correlate with target ordering on the instruction. For instance, if CNOT instruction has the control qubit on the first index and target qubit on the second index. Then ASCII symbols would have [“C”, “X”] to correlate a symbol with that index.

Raises:

ValueError – qubit_count is less than 1, ascii_symbols are None, or ascii_symbols length != qubit_count

adjoint() → list[Gate]

Returns a list of gates that implement the adjoint of this gate.

This is a list because some gates do not have an inverse defined by a single existing gate.

Returns:

list[Gate] – The gates comprising the adjoint of this gate.

static fixed_qubit_count() → int

Returns the number of qubits this quantum operator acts on, if instances are guaranteed to act on the same number of qubits.

If different instances can act on a different number of qubits, this method returns NotImplemented.

Returns:

int – The number of qubits this quantum operator acts on.

to_matrix() → ndarray

Returns a matrix representation of the quantum operator.

Parameters:

• *args (Any) – Not Implemented.

• **kwargs (Any) – Not Implemented.

Raises:

NotImplementError – Not Implemented.

Returns:

np.ndarray – A matrix representation of the quantum operator

static y(target: QubitSetInput, *, control: QubitSetInput | None = None, control_state: BasisStateInput | None = None, power: float = 1) → Iterable[Instruction]

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 (Optional[QubitSetInput]) – Control qubit(s). Default None.

• control_state (Optional[BasisStateInput]) – 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.

Returns:

Iterable[Instruction] – Iterable of Y instructions.

Examples

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

class YY(angle: FreeParameterExpression | float)

Bases: AngledGate

Ising YY coupling gate.

Unitary matrix:

\[\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}\]

Reference: https://arxiv.org/abs/1707.06356

Parameters:

angle (Union[FreeParameterExpression, float]) – angle in radians.

Initializes an AngledGate.

Parameters:

• angle (Union[FreeParameterExpression, float]) – The angle of the gate in radians or expression representation.

• qubit_count (Optional[int]) – The number of qubits that this gate interacts with.

• ascii_symbols (Sequence[str]) – ASCII string symbols for the gate. These are used when printing a diagram of a circuit. The length must be the same as qubit_count, and index ordering is expected to correlate with the target ordering on the instruction. For instance, if a CNOT instruction has the control qubit on the first index and target qubit on the second index, the ASCII symbols should have ["C", "X"] to correlate a symbol with that index.

Raises:

ValueError – If the qubit_count is less than 1, ascii_symbols are None, or ascii_symbols length != qubit_count, or angle is None

bind_values(**kwargs) → AngledGate

Takes in parameters and attempts to assign them to values.

Returns:

AngledGate – A new Gate of the same type with the requested parameters bound.

Raises:

NotImplementedError – Subclasses should implement this function.

static fixed_qubit_count() → int

Returns the number of qubits this quantum operator acts on, if instances are guaranteed to act on the same number of qubits.

If different instances can act on a different number of qubits, this method returns NotImplemented.

Returns:

int – The number of qubits this quantum operator acts on.

to_matrix() → ndarray

Returns a matrix representation of this gate.

Returns:

np.ndarray – The matrix representation of this gate.

static yy(target1: QubitInput, target2: QubitInput, angle: FreeParameterExpression | float, *, control: QubitSetInput | None = None, control_state: BasisStateInput | None = None, power: float = 1) → Instruction

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 (Union[FreeParameterExpression, float]) – angle in radians.

• control (Optional[QubitSetInput]) – Control qubit(s). Default None.

• control_state (Optional[BasisStateInput]) – 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.

Returns:

Instruction – YY instruction.

Examples

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

class Z

Bases: Gate

Pauli-Z gate.

Unitary matrix:

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

Initializes a Gate.

Parameters:

• qubit_count (Optional[int]) – Number of qubits this gate interacts with.

• ascii_symbols (Sequence[str]) – ASCII string symbols for the gate. These are used when printing a diagram of circuits. Length must be the same as qubit_count, and index ordering is expected to correlate with target ordering on the instruction. For instance, if CNOT instruction has the control qubit on the first index and target qubit on the second index. Then ASCII symbols would have [“C”, “X”] to correlate a symbol with that index.

Raises:

ValueError – qubit_count is less than 1, ascii_symbols are None, or ascii_symbols length != qubit_count

adjoint() → list[Gate]

Returns a list of gates that implement the adjoint of this gate.

This is a list because some gates do not have an inverse defined by a single existing gate.

Returns:

list[Gate] – The gates comprising the adjoint of this gate.

static fixed_qubit_count() → int

Returns the number of qubits this quantum operator acts on, if instances are guaranteed to act on the same number of qubits.

If different instances can act on a different number of qubits, this method returns NotImplemented.

Returns:

int – The number of qubits this quantum operator acts on.

to_matrix() → ndarray

Returns a matrix representation of the quantum operator.

Parameters:

• *args (Any) – Not Implemented.

• **kwargs (Any) – Not Implemented.

Raises:

NotImplementError – Not Implemented.

Returns:

np.ndarray – A matrix representation of the quantum operator

static z(target: QubitSetInput, *, control: QubitSetInput | None = None, control_state: BasisStateInput | None = None, power: float = 1) → Iterable[Instruction]

Pauli-Z gate.

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

Parameters:

• target (QubitSetInput) – Target qubit(s)

• control (Optional[QubitSetInput]) – Control qubit(s). Default None.

• control_state (Optional[BasisStateInput]) – 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.

Returns:

Iterable[Instruction] – Iterable of Z instructions.

Examples

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

class ZZ(angle: FreeParameterExpression | float)

Bases: AngledGate

Ising ZZ coupling gate.

Unitary matrix:

\[\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}\]

Reference: https://arxiv.org/abs/1707.06356

Parameters:

angle (Union[FreeParameterExpression, float]) – angle in radians.

Initializes an AngledGate.

Parameters:

• angle (Union[FreeParameterExpression, float]) – The angle of the gate in radians or expression representation.

• qubit_count (Optional[int]) – The number of qubits that this gate interacts with.

• ascii_symbols (Sequence[str]) – ASCII string symbols for the gate. These are used when printing a diagram of a circuit. The length must be the same as qubit_count, and index ordering is expected to correlate with the target ordering on the instruction. For instance, if a CNOT instruction has the control qubit on the first index and target qubit on the second index, the ASCII symbols should have ["C", "X"] to correlate a symbol with that index.

Raises:

ValueError – If the qubit_count is less than 1, ascii_symbols are None, or ascii_symbols length != qubit_count, or angle is None

bind_values(**kwargs) → AngledGate

Takes in parameters and attempts to assign them to values.

Returns:

AngledGate – A new Gate of the same type with the requested parameters bound.

Raises:

NotImplementedError – Subclasses should implement this function.

static fixed_qubit_count() → int

Returns the number of qubits this quantum operator acts on, if instances are guaranteed to act on the same number of qubits.

If different instances can act on a different number of qubits, this method returns NotImplemented.

Returns:

int – The number of qubits this quantum operator acts on.

to_matrix() → ndarray

Returns a matrix representation of the quantum operator.

Parameters:

• *args (Any) – Not Implemented.

• **kwargs (Any) – Not Implemented.

Raises:

NotImplementError – Not Implemented.

Returns:

np.ndarray – A matrix representation of the quantum operator

static zz(target1: QubitInput, target2: QubitInput, angle: FreeParameterExpression | float, *, control: QubitSetInput | None = None, control_state: BasisStateInput | None = None, power: float = 1) → Instruction

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 (Union[FreeParameterExpression, float]) – angle in radians.

• control (Optional[QubitSetInput]) – Control qubit(s). Default None.

• control_state (Optional[BasisStateInput]) – 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.

Returns:

Instruction – ZZ instruction.

Examples

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