qrunch.quantum.gates.composite_gates

Composite gate functionality and implementations.

Functions

`combine_gates`(name, gates, *[, num_qubits])	Combine a sequence of gates into a single composite gate.
`compact_qubits`(gates)	Re-index the qubits in gates to be consecutive.
`composite_gate`(...)	Create a composite gate from a function that generates a sequence of gates.
`relocate_gates`(gates, qubit_map)	Relocate a sequence of gates by mapping qubit indices according to a given qubit map.

Classes

`CPGate`	Two qubit controlled phase gate.
`CZGate`	Two qubit controlled Z-gate (CZ).
`DoubleExcitationGate`	Four qubit gate for creating double excitation evolutions.
`DoubleFermionicExcitationGate`	Four qubit gate for creating double fermionic excitation evolutions.
`HGate`	Single qubit Hadamard gate.
`InverseQuantumFourierTransformGate`	Inverse Quantum Fourier Transform (IQFT) gate acting on \(n\) qubits.
`SGate`	Single qubit S-gate.
`SWAPGate`	Two qubit SWAP-gate.
`SdgGate`	Single qubit \(S^\dagger\)-gate.
`SingleExcitationGate`	Two qubit gate for creating single excitation evolutions.
`SingleFermionicExcitationGate`	Two qubit gate for creating single fermionic excitation evolutions.
`ToffoliGate`	Toffoli gate, also known as Controlled-Controlled-X gate.
`XGate`	Single qubit NOT- or X-gate.
`XYGate`	Two qubit gate for creating an XX+YY interaction gate, also known as an XY-gate.
`YGate`	Single qubit Y-gate.
`ZGate`	Single qubit Z-gate.

class CPGate

Bases: CompositeGate, GateEncodingMixin

Two qubit controlled phase gate.

Applies a phase rotation of \(e^{i\phi}\) to the \(|11\rangle\) state.

Circuit form:

────●────
    │
  ┌─┴──┐
──┤P(φ)├──
  └────┘

Matrix representation in the basis \((|00\rangle, |01\rangle, |10\rangle, |11\rangle)\):

\[\begin{split}\text{CP}(\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}\]

__init__(angle: float | Parameter | ParameterExpression, control_qubit_index: int, target_qubit_index: int) → None

Initialize a CP-gate for a control and target qubit.

Parameters:

angle (float | Parameter | ParameterExpression) – The phase angle \(\phi\) to apply.
control_qubit_index (int) – Index of the control qubit.
target_qubit_index (int) – Index of the target qubit.

Return type:

None

static active_qubits(gates: Iterable[Gate]) → set[int]

Return the active qubits in a sequence of gates.

Parameters:: gates (Iterable[Gate]) – Sequence of gates.
Return type:: set[int]

commutes_with_pauli_string(pauli_string: PauliString) → bool

Check if gate commutes with the given pauli string. Default is False.

The default implementation always returns False. So False is considered a safe answer. An only True should be trusted.

Parameters:: pauli_string (PauliString) – Pauli string to check commutation for.
Return type:: bool

classmethod decode(data: dict[str, Any]) → T

Decode a dictionary.

Parameters:: data (dict[str, Any]) – The dictionary representation.
Return type:: T

encode() → dict[str, Any]

Encode the instance into a dictionary.

Return type:: dict[str, Any]

flatten() → Iterator[Gate]

Flatten the gate into a list of primitive gates.

Return type:: Iterator[Gate]

property gates: list[Gate]

List of gates that the composite gate is constructed from.

The list of gates are the immediate sub-gates that the composite gate is constructed from, not necessarily the primitive gates. To expand the gate down to primitive gates use the primitive_gates property instead.

invert() → Self

Get the inverse of the gate.

Return type:: Self

is_fully_specified() → bool

Check if all parameters have been specified.

Return type:: bool

name: str

property parameters: list[float | Parameter | ParameterExpression]: List of all parameters available.

property qubit_indices: tuple[int, ...]: Indices of the qubits that gate is working on.

relocate(new_indices: Mapping[int, int]) → Self

Relocate the gate to new qubit indices.

Parameters:: new_indices (Mapping[int, int]) – Mapping between current qubit indices and new qubit indices.
Returns:: New gate with the qubit indices updated.
Return type:: Gate

static sorted_active_qubits(gates: Iterable[Gate]) → tuple[int, ...]

Return the active qubits in a sequence of gates, sorted, as a tuple.

Parameters:: gates (Iterable[Gate]) – Sequence of gates.
Return type:: tuple[int, …]

symbols(*, max_number_of_decimals: int | None = None) → list[str]

Symbols for represent the gate in a circuit.

Parameters:: max_number_of_decimals (int | None) – Maximum number of decimals to use for floats in the symbols. Defaults to None.
Return type:: list[str]

with_specified_parameters(parameter_value_pairs: dict[Parameter, float | ParameterExpression]) → Self

Assign parameters with the given float value.

Parameters:: parameter_value_pairs (dict[Parameter, float | ParameterExpression])
Return type:: Self

class CZGate

Bases: CompositeGate, GateEncodingMixin

Two qubit controlled Z-gate (CZ). The CZ gate acts on two qubits as.

\[\begin{split}\text{CZ} |00\rangle = |00\rangle, \\ \text{CZ} |01\rangle = |01\rangle, \\ \text{CZ} |10\rangle = |10\rangle, \\ \text{CZ} |11\rangle = -|11\rangle.\end{split}\]

Circuit form:

────●────
    │
  ┌─┴─┐
──┤ Z ├──
  └───┘

Matrix representation in the basis \((|00\rangle, |01\rangle, |10\rangle, |11\rangle)\):

\[\begin{split}\text{CX} = \begin{bmatrix} 1 & 0 & 0 & 0 \\ 0 & 1 & 0 & 0 \\ 0 & 0 & 1 & 0 \\ 0 & 0 & 0 & -1 \end{bmatrix}\end{split}\]

__init__(control_qubit_index: int, target_qubit_index: int) → None

Initialize a CZ-gate for a control and target qubit.

Indices control_qubit_index and target_qubit_index, respectively.

Parameters:

control_qubit_index (int) – Index of the control qubit.
target_qubit_index (int) – Index of the qubit for the Z-gate to be conditionally applied on.

Return type:

None

static active_qubits(gates: Iterable[Gate]) → set[int]

Return the active qubits in a sequence of gates.

Parameters:: gates (Iterable[Gate]) – Sequence of gates.
Return type:: set[int]

commutes_with_pauli_string(pauli_string: PauliString) → bool

Check if gate commutes with the given pauli string. Default is False.

The default implementation always returns False. So False is considered a safe answer. An only True should be trusted.

Parameters:: pauli_string (PauliString) – Pauli string to check commutation for.
Return type:: bool

classmethod decode(data: dict[str, Any]) → T

Decode a dictionary.

Parameters:: data (dict[str, Any]) – The dictionary representation.
Return type:: T

encode() → dict[str, Any]

Encode the instance into a dictionary.

Return type:: dict[str, Any]

flatten() → Iterator[Gate]

Flatten the gate into a list of primitive gates.

Return type:: Iterator[Gate]

property gates: list[Gate]

List of gates that the composite gate is constructed from.

The list of gates are the immediate sub-gates that the composite gate is constructed from, not necessarily the primitive gates. To expand the gate down to primitive gates use the primitive_gates property instead.

invert() → Self

Get the inverse of the gate.

Return type:: Self

is_fully_specified() → bool

Check if all parameters have been specified.

Return type:: bool

name: str

property parameters: list[float | Parameter | ParameterExpression]: List of all parameters available.

property qubit_indices: tuple[int, ...]: Indices of the qubits that gate is working on.

relocate(new_indices: Mapping[int, int]) → Self

Relocate the gate to new qubit indices.

Parameters:: new_indices (Mapping[int, int]) – Mapping between current qubit indices and new qubit indices.
Returns:: New gate with the qubit indices updated.
Return type:: Gate

static sorted_active_qubits(gates: Iterable[Gate]) → tuple[int, ...]

Return the active qubits in a sequence of gates, sorted, as a tuple.

Parameters:: gates (Iterable[Gate]) – Sequence of gates.
Return type:: tuple[int, …]

symbols(*, max_number_of_decimals: int | None = None) → list[str]

Symbols for represent the gate in a circuit.

Parameters:: max_number_of_decimals (int | None) – Maximum number of decimals to use for floats in the symbols. Defaults to None.
Return type:: list[str]

with_specified_parameters(parameter_value_pairs: dict[Parameter, float | ParameterExpression]) → Self

Assign parameters with the given float value.

Parameters:: parameter_value_pairs (dict[Parameter, float | ParameterExpression])
Return type:: Self

class DoubleExcitationGate

Bases: CompositeGate, GateEncodingMixin

Four qubit gate for creating double excitation evolutions.

A double excitation evolution is generated by operators

\[A_{pqrs} = e^{\theta (Q_p^\dagger Q_q^\dagger Q_r Q_s - Q_r^\dagger Q_s^\dagger Q_p Q_q)}\]

where \(Q_i\) and \(Q_i^\dagger\) removes and adds one qubit excitation for the \(i\)’th site, respectively. The operator, therefore, either fully or partially removes excitations from sites p and q and adds them to sites r and s or vice versa. \(\theta\) parametrizes the degree of double excitation evolution.

Circuit form:

  ┌───────┐
──┤DEE1(θ)├──
  └───┬───┘
  ┌───┴───┐
──┤DEE2(θ)├──
  └───┬───┘
  ┌───┴───┐
──┤DEE3(θ)├──
  └───┬───┘
  ┌───┴───┐
──┤DEE4(θ)├──
  └───────┘

Identity outside the basis \((|0011\rangle, |1100\rangle)\), where it has matrix representation:

\[\begin{split}\text{DEE}(\theta) = \begin{bmatrix} \cos\theta & \sin\theta \\ -\sin\theta & \cos\theta \\ \end{bmatrix}\end{split}\]

__init__(parameter: Parameter | ParameterExpression | float, creation_qubit_index_1: int, creation_qubit_index_2: int, annihilation_qubit_index_1: int, annihilation_qubit_index_2: int) → None

Initialize a double excitation evolution for two qubits.

The indices are creation_qubit_index_1 as p, creation_qubit_index_2 as q, annihilation_qubit_index_1 as r, and annihilation_qubit_index_2 as s.

Uses Figure 2d in https://arxiv.org/pdf/1902.10171 with the parameters corrected to match the operator above.

Parameters:

parameter (Parameter | ParameterExpression | float) – Parameter \(\theta\) determining the degree of double excitation evolution.
creation_qubit_index_1 (int) – Index \(p\) of the first qubit where a qubit excitation is potentially added.
creation_qubit_index_2 (int) – Index \(q\) of the second qubit where a qubit excitation is potentially added.
annihilation_qubit_index_1 (int) – Index \(r\) of the first qubit where a qubit excitation is potentially removed.
annihilation_qubit_index_2 (int) – Index \(s\) of the second qubit where a qubit excitation is potentially removed.

Return type:

None

static active_qubits(gates: Iterable[Gate]) → set[int]

Return the active qubits in a sequence of gates.

Parameters:: gates (Iterable[Gate]) – Sequence of gates.
Return type:: set[int]

commutes_with_pauli_string(pauli_string: PauliString) → bool

Check if gate commutes with the given pauli string.

Parameters:: pauli_string (PauliString) – Pauli string to check commutation for.
Return type:: bool

classmethod decode(data: dict[str, Any]) → T

Decode a dictionary.

Parameters:: data (dict[str, Any]) – The dictionary representation.
Return type:: T

encode() → dict[str, Any]

Encode the instance into a dictionary.

Return type:: dict[str, Any]

flatten() → Iterator[Gate]

Flatten the gate into a list of primitive gates.

Return type:: Iterator[Gate]

property gates: list[Gate]

List of gates that the composite gate is constructed from.

The list of gates are the immediate sub-gates that the composite gate is constructed from, not necessarily the primitive gates. To expand the gate down to primitive gates use the primitive_gates property instead.

invert() → Self

Get the inverse of the gate.

Return type:: Self

is_fully_specified() → bool

Check if all parameters have been specified.

Return type:: bool

name: str

property parameters: list[float | Parameter | ParameterExpression]: List of all parameters available.

property qubit_indices: tuple[int, ...]: Indices of the qubits that gate is working on.

relocate(new_indices: Mapping[int, int]) → Self

Relocate the gate to new qubit indices.

Parameters:: new_indices (Mapping[int, int]) – Mapping between current qubit indices and new qubit indices.
Returns:: New gate with the qubit indices updated.
Return type:: Gate

static sorted_active_qubits(gates: Iterable[Gate]) → tuple[int, ...]

Return the active qubits in a sequence of gates, sorted, as a tuple.

Parameters:: gates (Iterable[Gate]) – Sequence of gates.
Return type:: tuple[int, …]

symbols(*, max_number_of_decimals: int | None = None) → list[str]

Symbols for represent the gate in a circuit.

Parameters:: max_number_of_decimals (int | None) – Maximum number of decimals to use for floats in the symbols. Defaults to None.
Return type:: list[str]

with_specified_parameters(parameter_value_pairs: dict[Parameter, float | ParameterExpression]) → DoubleExcitationGate

Assign parameters with the given float value.

Parameters:: parameter_value_pairs (dict[Parameter, float | ParameterExpression])
Return type:: DoubleExcitationGate

class DoubleFermionicExcitationGate

Bases: CompositeGate, GateEncodingMixin

Four qubit gate for creating double fermionic excitation evolutions.

A double fermionic excitation evolution is generated by operators

\[A_{pqrs} = e^{\theta (a_p^\dagger a_q^\dagger a_r a_s - a_r^\dagger a_s^\dagger a_p a_q)} = e^{\theta (Q_p^\dagger Q_q^\dagger Q_r Q_s - Q_r^\dagger Q_s^\dagger Q_p Q_q) \prod_k Z_k}\]

where \(k\) goes through all indices between the smallest two and largest two indices, and where \(a_i\) and \(a_i^\dagger\) denote fermionic annihilation and creation operators at the \(i\)’th site, respectively. The operator, therefore, either fully or partially removes an excitation from sites p and q and adds them to sites r and s or vice versa. \(\theta\) parametrizes the degree of double excitation evolution. (Compare with DoubleExcitationGate.)

Circuit form:

  ┌───────┐
──┤DFE1(θ)├──
  └───┬───┘
  ┌───┴───┐
──┤DFE2(θ)├──
  └───┬───┘
  ┌───┴───┐
──┤DFE3(θ)├──
  └───┬───┘
  ┌───┴───┐
──┤DFE4(θ)├──
  └───────┘

Identity outside the basis \((|0011\rangle, |1100\rangle)\), where it has matrix representation:

\[\begin{split}\text{DFE}(\theta) = \begin{bmatrix} \cos\theta & \sin\theta \\ -\sin\theta & \cos\theta \\ \end{bmatrix}\end{split}\]

But, in contrast to DoubleExcitationGate, this gate also keeps track of the number of 1’s between the first two sites and the last two sites. (See SingleFermionicExcitationGate.)

__init__(parameter: Parameter | ParameterExpression | float, creation_qubit_index_1: int, creation_qubit_index_2: int, annihilation_qubit_index_1: int, annihilation_qubit_index_2: int) → None

Initialize a double fermionic excitation evolution for two qubits.

The indices are creation_qubit_index_1 as p, creation_qubit_index_2 as q, annihilation_qubit_index_1 as r, and annihilation_qubit_index_2 as s.

Uses figure 8 in https://arxiv.org/pdf/2005.14475.

Parameters:

parameter (Parameter | ParameterExpression | float) – Parameter \(\theta\) determining the degree of double fermionic excitation evolution.
creation_qubit_index_1 (int) – Index \(p\) of the first qubit where a qubit excitation is potentially added.
creation_qubit_index_2 (int) – Index \(q\) of the second qubit where a qubit excitation is potentially added.
annihilation_qubit_index_1 (int) – Index \(r\) of the first qubit where a qubit excitation is potentially removed.
annihilation_qubit_index_2 (int) – Index \(s\) of the second qubit where a qubit excitation is potentially removed.

Return type:

None

static active_qubits(gates: Iterable[Gate]) → set[int]

Return the active qubits in a sequence of gates.

Parameters:: gates (Iterable[Gate]) – Sequence of gates.
Return type:: set[int]

commutes_with_pauli_string(pauli_string: PauliString) → bool

Check if gate commutes with the given pauli string. Default is False.

The default implementation always returns False. So False is considered a safe answer. An only True should be trusted.

Parameters:: pauli_string (PauliString) – Pauli string to check commutation for.
Return type:: bool

classmethod decode(data: dict[str, Any]) → T

Decode a dictionary.

Parameters:: data (dict[str, Any]) – The dictionary representation.
Return type:: T

encode() → dict[str, Any]

Encode the instance into a dictionary.

Return type:: dict[str, Any]

flatten() → Iterator[Gate]

Flatten the gate into a list of primitive gates.

Return type:: Iterator[Gate]

property gates: list[Gate]

List of gates that the composite gate is constructed from.

The list of gates are the immediate sub-gates that the composite gate is constructed from, not necessarily the primitive gates. To expand the gate down to primitive gates use the primitive_gates property instead.

invert() → Self

Get the inverse of the gate.

Return type:: Self

is_fully_specified() → bool

Check if all parameters have been specified.

Return type:: bool

name: str

property parameters: list[float | Parameter | ParameterExpression]: List of all parameters available.

property qubit_indices: tuple[int, ...]: Indices of the qubits that gate is working on.

relocate(new_indices: Mapping[int, int]) → Self

Relocate the gate to new qubit indices.

Parameters:: new_indices (Mapping[int, int]) – Mapping between current qubit indices and new qubit indices.
Returns:: New gate with the qubit indices updated.
Return type:: Gate

static sorted_active_qubits(gates: Iterable[Gate]) → tuple[int, ...]

Return the active qubits in a sequence of gates, sorted, as a tuple.

Parameters:: gates (Iterable[Gate]) – Sequence of gates.
Return type:: tuple[int, …]

symbols(*, max_number_of_decimals: int | None = None) → list[str]

Symbols for represent the gate in a circuit.

Parameters:: max_number_of_decimals (int | None) – Maximum number of decimals to use for floats in the symbols. Defaults to None.
Return type:: list[str]

with_specified_parameters(parameter_value_pairs: dict[Parameter, float | ParameterExpression]) → Self

Assign parameters with the given float value.

Parameters:: parameter_value_pairs (dict[Parameter, float | ParameterExpression])
Return type:: Self

class HGate

Bases: CompositeGate, GateEncodingMixin

Single qubit Hadamard gate. The Hadamard gate acts on qubit states as.

\[\begin{split}H|0\rangle = \frac{1}{\sqrt{2}}(|0\rangle + |1\rangle), \\ H|1\rangle = \frac{1}{\sqrt{2}}(|0\rangle - |1\rangle).\end{split}\]

Circuit form:

  ┌───┐
──┤ H ├──
  └───┘

Matrix representation in the basis \((|0\rangle, |1\rangle)\):

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

__init__(qubit_index: int) → None

Initialize an H-gate for a qubit with the given index qubit_index.

Parameters:: qubit_index (int) – Index of the qubit for the H-gate to act on.
Return type:: None

static active_qubits(gates: Iterable[Gate]) → set[int]

Return the active qubits in a sequence of gates.

Parameters:: gates (Iterable[Gate]) – Sequence of gates.
Return type:: set[int]

commutes_with_pauli_string(pauli_string: PauliString) → bool

Check if gate commutes with the given pauli string. Default is False.

The default implementation always returns False. So False is considered a safe answer. An only True should be trusted.

Parameters:: pauli_string (PauliString) – Pauli string to check commutation for.
Return type:: bool

classmethod decode(data: dict[str, Any]) → T

Decode a dictionary.

Parameters:: data (dict[str, Any]) – The dictionary representation.
Return type:: T

encode() → dict[str, Any]

Encode the instance into a dictionary.

Return type:: dict[str, Any]

flatten() → Iterator[Gate]

Flatten the gate into a list of primitive gates.

Return type:: Iterator[Gate]

property gates: list[Gate]

List of gates that the composite gate is constructed from.

The list of gates are the immediate sub-gates that the composite gate is constructed from, not necessarily the primitive gates. To expand the gate down to primitive gates use the primitive_gates property instead.

invert() → Self

Get the inverse of the gate.

Return type:: Self

is_fully_specified() → bool

Check if all parameters have been specified.

Return type:: bool

name: str

property parameters: list[float | Parameter | ParameterExpression]: List of all parameters available.

property qubit_indices: tuple[int, ...]: Indices of the qubits that gate is working on.

relocate(new_indices: Mapping[int, int]) → Self

Relocate the gate to new qubit indices.

Parameters:: new_indices (Mapping[int, int]) – Mapping between current qubit indices and new qubit indices.
Returns:: New gate with the qubit indices updated.
Return type:: Gate

static sorted_active_qubits(gates: Iterable[Gate]) → tuple[int, ...]

Return the active qubits in a sequence of gates, sorted, as a tuple.

Parameters:: gates (Iterable[Gate]) – Sequence of gates.
Return type:: tuple[int, …]

symbols(*, max_number_of_decimals: int | None = None) → list[str]

Symbols for represent the gate in a circuit.

Parameters:: max_number_of_decimals (int | None) – Maximum number of decimals to use for floats in the symbols. Defaults to None.
Return type:: list[str]

with_specified_parameters(parameter_value_pairs: dict[Parameter, float | ParameterExpression]) → Self

Assign parameters with the given float value.

Parameters:: parameter_value_pairs (dict[Parameter, float | ParameterExpression])
Return type:: Self

class InverseQuantumFourierTransformGate

Bases: CompositeGate, GateEncodingMixin

Inverse Quantum Fourier Transform (IQFT) gate acting on \(n\) qubits.

The Inverse Quantum Fourier Transform is the inverse of the Quantum Fourier Transform (QFT), which maps computational basis states as:

\[\text{IQFT} |j\rangle = \frac{1}{\sqrt{N}} \sum_{k=0}^{N-1} e^{-2\pi i jk/N} |k\rangle,\]

where \(N = 2^n\) and \(n\) is the number of qubits.

Circuit form for 3 qubits:

  ┌──────┐
──┤IQFT_0├──
  └──┬───┘
  ┌──┴───┐
──┤IQFT_1├──
  └──┬───┘
  ┌──┴───┐
──┤IQFT_2├──
  └──────┘

__init__(*qubit_indices: int) → None

Initialize an Inverse Quantum Fourier Transform gate for the given qubit indices.

Parameters:: qubit_indices (int) – Tuple of qubit indices for the IQFT to act on, ordered from most significant to least significant qubit.
Return type:: None

static active_qubits(gates: Iterable[Gate]) → set[int]

Return the active qubits in a sequence of gates.

Parameters:: gates (Iterable[Gate]) – Sequence of gates.
Return type:: set[int]

commutes_with_pauli_string(pauli_string: PauliString) → bool

Check if gate commutes with the given pauli string. Default is False.

The default implementation always returns False. So False is considered a safe answer. An only True should be trusted.

Parameters:: pauli_string (PauliString) – Pauli string to check commutation for.
Return type:: bool

classmethod decode(data: dict[str, Any]) → T

Decode a dictionary.

Parameters:: data (dict[str, Any]) – The dictionary representation.
Return type:: T

encode() → dict[str, Any]

Encode the instance into a dictionary.

Return type:: dict[str, Any]

flatten() → Iterator[Gate]

Flatten the gate into a list of primitive gates.

Return type:: Iterator[Gate]

property gates: list[Gate]

List of gates that the composite gate is constructed from.

The list of gates are the immediate sub-gates that the composite gate is constructed from, not necessarily the primitive gates. To expand the gate down to primitive gates use the primitive_gates property instead.

invert() → Self

Get the inverse of the gate.

Return type:: Self

is_fully_specified() → bool

Check if all parameters have been specified.

Return type:: bool

name: str

property parameters: list[float | Parameter | ParameterExpression]: List of all parameters available.

property qubit_indices: tuple[int, ...]: Indices of the qubits that gate is working on.

relocate(new_indices: Mapping[int, int]) → Self

Relocate the gate to new qubit indices.

Parameters:: new_indices (Mapping[int, int]) – Mapping between current qubit indices and new qubit indices.
Returns:: New gate with the qubit indices updated.
Return type:: Gate

static sorted_active_qubits(gates: Iterable[Gate]) → tuple[int, ...]

Return the active qubits in a sequence of gates, sorted, as a tuple.

Parameters:: gates (Iterable[Gate]) – Sequence of gates.
Return type:: tuple[int, …]

symbols(*, max_number_of_decimals: int | None = None) → list[str]

Symbols for represent the gate in a circuit.

Parameters:: max_number_of_decimals (int | None) – Maximum number of decimals to use for floats in the symbols. Defaults to None.
Return type:: list[str]

with_specified_parameters(parameter_value_pairs: dict[Parameter, float | ParameterExpression]) → Self

Assign parameters with the given float value.

Parameters:: parameter_value_pairs (dict[Parameter, float | ParameterExpression])
Return type:: Self

class SGate

Bases: CompositeGate, GateEncodingMixin

Single qubit S-gate.

The operator form of the S-gate is the pauli \(\sqrt(Z)\) operator, and has the action.

\[\begin{split}S|0\rangle = |0\rangle, \\ S|1\rangle = i|1\rangle.\end{split}\]

Circuit form:

  ┌───┐
──┤ S ├──
  └───┘

Matrix representation in the basis \((|0\rangle, |1\rangle)\):

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

__init__(qubit_index: int) → None

Initialize a S-gate for a qubit with the given index qubit_index.

Parameters:: qubit_index (int) – Index of the qubit for the S-gate to act on.
Return type:: None

static active_qubits(gates: Iterable[Gate]) → set[int]

Return the active qubits in a sequence of gates.

Parameters:: gates (Iterable[Gate]) – Sequence of gates.
Return type:: set[int]

commutes_with_pauli_string(pauli_string: PauliString) → bool

Check if gate commutes with the given pauli string. Default is False.

The default implementation always returns False. So False is considered a safe answer. An only True should be trusted.

Parameters:: pauli_string (PauliString) – Pauli string to check commutation for.
Return type:: bool

classmethod decode(data: dict[str, Any]) → T

Decode a dictionary.

Parameters:: data (dict[str, Any]) – The dictionary representation.
Return type:: T

encode() → dict[str, Any]

Encode the instance into a dictionary.

Return type:: dict[str, Any]

flatten() → Iterator[Gate]

Flatten the gate into a list of primitive gates.

Return type:: Iterator[Gate]

property gates: list[Gate]

List of gates that the composite gate is constructed from.

The list of gates are the immediate sub-gates that the composite gate is constructed from, not necessarily the primitive gates. To expand the gate down to primitive gates use the primitive_gates property instead.

invert() → Self

Get the inverse of the gate.

Return type:: Self

is_fully_specified() → bool

Check if all parameters have been specified.

Return type:: bool

name: str

property parameters: list[float | Parameter | ParameterExpression]: List of all parameters available.

property qubit_indices: tuple[int, ...]: Indices of the qubits that gate is working on.

relocate(new_indices: Mapping[int, int]) → Self

Relocate the gate to new qubit indices.

Parameters:: new_indices (Mapping[int, int]) – Mapping between current qubit indices and new qubit indices.
Returns:: New gate with the qubit indices updated.
Return type:: Gate

static sorted_active_qubits(gates: Iterable[Gate]) → tuple[int, ...]

Return the active qubits in a sequence of gates, sorted, as a tuple.

Parameters:: gates (Iterable[Gate]) – Sequence of gates.
Return type:: tuple[int, …]

symbols(*, max_number_of_decimals: int | None = None) → list[str]

Symbols for represent the gate in a circuit.

Parameters:: max_number_of_decimals (int | None) – Maximum number of decimals to use for floats in the symbols. Defaults to None.
Return type:: list[str]

with_specified_parameters(parameter_value_pairs: dict[Parameter, float | ParameterExpression]) → Self

Assign parameters with the given float value.

Parameters:: parameter_value_pairs (dict[Parameter, float | ParameterExpression])
Return type:: Self

class SWAPGate

Bases: CompositeGate, GateEncodingMixin

Two qubit SWAP-gate. The SWAP-gate acts on two qubits as.

\[\begin{split}\text{SWAP} |00\rangle = |00\rangle, \\ \text{SWAP} |01\rangle = |10\rangle, \\ \text{SWAP} |10\rangle = |01\rangle, \\ \text{SWAP} |11\rangle = |11\rangle.\end{split}\]

Circuit form:

──╳──
  │
  │
──╳──

Matrix representation in the basis \((|00\rangle, |01\rangle, |10\rangle, |11\rangle)\):

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

__init__(first_qubit_index: int, second_qubit_index: int) → None

Initialize a SWAP-gate for two qubits.

Indices first_qubit_index and second_qubit_index, respectively.

Parameters:

first_qubit_index (int) – Index of the control qubit.
second_qubit_index (int) – Index of the qubit for the X-gate to be conditionally applied on.

Return type:

None

static active_qubits(gates: Iterable[Gate]) → set[int]

Return the active qubits in a sequence of gates.

Parameters:: gates (Iterable[Gate]) – Sequence of gates.
Return type:: set[int]

commutes_with_pauli_string(pauli_string: PauliString) → bool

Check if gate commutes with the given pauli string. Default is False.

The default implementation always returns False. So False is considered a safe answer. An only True should be trusted.

Parameters:: pauli_string (PauliString) – Pauli string to check commutation for.
Return type:: bool

classmethod decode(data: dict[str, Any]) → T

Decode a dictionary.

Parameters:: data (dict[str, Any]) – The dictionary representation.
Return type:: T

encode() → dict[str, Any]

Encode the instance into a dictionary.

Return type:: dict[str, Any]

flatten() → Iterator[Gate]

Flatten the gate into a list of primitive gates.

Return type:: Iterator[Gate]

property gates: list[Gate]

List of gates that the composite gate is constructed from.

The list of gates are the immediate sub-gates that the composite gate is constructed from, not necessarily the primitive gates. To expand the gate down to primitive gates use the primitive_gates property instead.

invert() → Self

Get the inverse of the gate.

Return type:: Self

is_fully_specified() → bool

Check if all parameters have been specified.

Return type:: bool

name: str

property parameters: list[float | Parameter | ParameterExpression]: List of all parameters available.

property qubit_indices: tuple[int, ...]: Indices of the qubits that gate is working on.

relocate(new_indices: Mapping[int, int]) → Self

Relocate the gate to new qubit indices.

Parameters:: new_indices (Mapping[int, int]) – Mapping between current qubit indices and new qubit indices.
Returns:: New gate with the qubit indices updated.
Return type:: Gate

static sorted_active_qubits(gates: Iterable[Gate]) → tuple[int, ...]

Return the active qubits in a sequence of gates, sorted, as a tuple.

Parameters:: gates (Iterable[Gate]) – Sequence of gates.
Return type:: tuple[int, …]

symbols(*, max_number_of_decimals: int | None = None) → list[str]

Symbols for represent the gate in a circuit.

Parameters:: max_number_of_decimals (int | None) – Maximum number of decimals to use for floats in the symbols. Defaults to None.
Return type:: list[str]

with_specified_parameters(parameter_value_pairs: dict[Parameter, float | ParameterExpression]) → Self

Assign parameters with the given float value.

Parameters:: parameter_value_pairs (dict[Parameter, float | ParameterExpression])
Return type:: Self

class SdgGate

Bases: CompositeGate, GateEncodingMixin

Single qubit \(S^\dagger\)-gate.

The operator form of the \(S^\dagger\)-gate is the pauli \(\sqrt(Z)^\dagger\) operator, and has the action.

\[\begin{split}S|0\rangle = |0\rangle, \\ S|1\rangle = -i|1\rangle.\end{split}\]

Circuit form:

  ┌───┐
──┤Sdg├──
  └───┘

Matrix representation in the basis \((|0\rangle, |1\rangle)\):

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

__init__(qubit_index: int) → None

Initialize an \(S^\dagger\)-gate for a qubit with the given index qubit_index.

Parameters:: qubit_index (int) – Index of the qubit for the \(S^\dagger\)-gate to act on.
Return type:: None

static active_qubits(gates: Iterable[Gate]) → set[int]

Return the active qubits in a sequence of gates.

Parameters:: gates (Iterable[Gate]) – Sequence of gates.
Return type:: set[int]

commutes_with_pauli_string(pauli_string: PauliString) → bool

Check if gate commutes with the given pauli string. Default is False.

The default implementation always returns False. So False is considered a safe answer. An only True should be trusted.

Parameters:: pauli_string (PauliString) – Pauli string to check commutation for.
Return type:: bool

classmethod decode(data: dict[str, Any]) → T

Decode a dictionary.

Parameters:: data (dict[str, Any]) – The dictionary representation.
Return type:: T

encode() → dict[str, Any]

Encode the instance into a dictionary.

Return type:: dict[str, Any]

flatten() → Iterator[Gate]

Flatten the gate into a list of primitive gates.

Return type:: Iterator[Gate]

property gates: list[Gate]

List of gates that the composite gate is constructed from.

The list of gates are the immediate sub-gates that the composite gate is constructed from, not necessarily the primitive gates. To expand the gate down to primitive gates use the primitive_gates property instead.

invert() → Self

Get the inverse of the gate.

Return type:: Self

is_fully_specified() → bool

Check if all parameters have been specified.

Return type:: bool

name: str

property parameters: list[float | Parameter | ParameterExpression]: List of all parameters available.

property qubit_indices: tuple[int, ...]: Indices of the qubits that gate is working on.

relocate(new_indices: Mapping[int, int]) → Self

Relocate the gate to new qubit indices.

Parameters:: new_indices (Mapping[int, int]) – Mapping between current qubit indices and new qubit indices.
Returns:: New gate with the qubit indices updated.
Return type:: Gate

static sorted_active_qubits(gates: Iterable[Gate]) → tuple[int, ...]

Return the active qubits in a sequence of gates, sorted, as a tuple.

Parameters:: gates (Iterable[Gate]) – Sequence of gates.
Return type:: tuple[int, …]

symbols(*, max_number_of_decimals: int | None = None) → list[str]

Symbols for represent the gate in a circuit.

Parameters:: max_number_of_decimals (int | None) – Maximum number of decimals to use for floats in the symbols. Defaults to None.
Return type:: list[str]

with_specified_parameters(parameter_value_pairs: dict[Parameter, float | ParameterExpression]) → Self

Assign parameters with the given float value.

Parameters:: parameter_value_pairs (dict[Parameter, float | ParameterExpression])
Return type:: Self

class SingleExcitationGate

Bases: CompositeGate, GateEncodingMixin

Two qubit gate for creating single excitation evolutions.

A single excitation evolution is generated by the operator

\[A_{pq} = e^{\theta (Q_p^\dagger Q_q - Q_q^\dagger Q_p)},\]

where \(Q_i\) and \(Q_i^\dagger\) removes and adds one qubit excitation for the \(i\)’th site, respectively. The operator, therefore, either fully or partially removes an excitation from site p and adds it to site q or vice versa. \(\theta\) parametrizes the degree of single excitation evolution.

Circuit form:

  ┌───────┐
──┤SEE1(θ)├──
  └───┬───┘
  ┌───┴───┐
──┤SEE2(θ)├──
  └───────┘

Matrix representation in the basis \((|00\rangle, |01\rangle, |10\rangle, |11\rangle)\):

\[\begin{split}\text{SEE}(\theta) = \begin{bmatrix} 1 & 0 & 0 & 0 \\ 0 & \cos\theta & -\sin\theta & 0 \\ 0 & \sin\theta & \cos\theta & 0 \\ 0 & 0 & 0 & 1 \end{bmatrix}\end{split}\]

I.e., identity outside the basis \((|01\rangle, |10\rangle)\), where it has matrix representation:

\[\begin{split}\text{SEE}(\theta) = \begin{bmatrix} \cos\theta & -\sin\theta \\ \sin\theta & \cos\theta \\ \end{bmatrix}\end{split}\]

__init__(parameter: Parameter | ParameterExpression | float, creation_qubit_index: int, annihilation_qubit_index: int) → None

Initialize a single excitation evolution for two qubits with the given indices.

creation_qubit_index as \(p\), annihilation_qubit_index as \(q\), and parameter as \(\theta\).

Parameters:

parameter (Parameter | ParameterExpression | float) – Parameter \(\theta\) determining the degree of single excitation evolution.
creation_qubit_index (int) – Index \(p\) of the qubit where a qubit excitation is partially added.
annihilation_qubit_index (int) – Index \(q\) of the qubit where a qubit excitation is partially removed.

Return type:

None

Uses figure 1 in https://arxiv.org/pdf/2011.10540.

static active_qubits(gates: Iterable[Gate]) → set[int]

Return the active qubits in a sequence of gates.

Parameters:: gates (Iterable[Gate]) – Sequence of gates.
Return type:: set[int]

commutes_with_pauli_string(pauli_string: PauliString) → bool

Check if gate commutes with the given pauli string.

Parameters:: pauli_string (PauliString) – Pauli string to check commutation for.
Return type:: bool

classmethod decode(data: dict[str, Any]) → T

Decode a dictionary.

Parameters:: data (dict[str, Any]) – The dictionary representation.
Return type:: T

encode() → dict[str, Any]

Encode the instance into a dictionary.

Return type:: dict[str, Any]

flatten() → Iterator[Gate]

Flatten the gate into a list of primitive gates.

Return type:: Iterator[Gate]

property gates: list[Gate]

List of gates that the composite gate is constructed from.

The list of gates are the immediate sub-gates that the composite gate is constructed from, not necessarily the primitive gates. To expand the gate down to primitive gates use the primitive_gates property instead.

invert() → Self

Get the inverse of the gate.

Return type:: Self

is_fully_specified() → bool

Check if all parameters have been specified.

Return type:: bool

name: str

property parameters: list[float | Parameter | ParameterExpression]: List of all parameters available.

property qubit_indices: tuple[int, ...]: Indices of the qubits that gate is working on.

relocate(new_indices: Mapping[int, int]) → Self

Relocate the gate to new qubit indices.

Parameters:: new_indices (Mapping[int, int]) – Mapping between current qubit indices and new qubit indices.
Returns:: New gate with the qubit indices updated.
Return type:: Gate

static sorted_active_qubits(gates: Iterable[Gate]) → tuple[int, ...]

Return the active qubits in a sequence of gates, sorted, as a tuple.

Parameters:: gates (Iterable[Gate]) – Sequence of gates.
Return type:: tuple[int, …]

symbols(*, max_number_of_decimals: int | None = None) → list[str]

Symbols for represent the gate in a circuit.

Parameters:: max_number_of_decimals (int | None) – Maximum number of decimals to use for floats in the symbols. Defaults to None.
Return type:: list[str]

with_specified_parameters(parameter_value_pairs: dict[Parameter, float | ParameterExpression]) → SingleExcitationGate

Assign parameters with the given float value.

Parameters:: parameter_value_pairs (dict[Parameter, float | ParameterExpression])
Return type:: SingleExcitationGate

class SingleFermionicExcitationGate

Bases: CompositeGate, GateEncodingMixin

Two qubit gate for creating single fermionic excitation evolutions.

A single fermionic excitation evolution is generated by the operator

\[A_{pq} = e^{\theta (a_p^\dagger a_q - a_q^\dagger a_p)} = e^{\theta (Q_p^\dagger Q_q - Q_q^\dagger Q_p) \prod_k Z_k},\]

where \(k\) goes through all indices between p and q in the product, and where \(a_i\) and \(a_i^\dagger\) denote fermionic annihilation and creation operators at the \(i\)’th site, respectively. The operator, therefore, either fully or partially removes an excitation from site p and adds it to site q or vice versa. \(\theta\) parametrizes the degree of single excitation evolution. (Compare with SingleExcitationGate.)

Circuit form:

  ┌───────┐
──┤SFE1(θ)├──
  └───┬───┘
  ┌───┴───┐
──┤SFE2(θ)├──
  └───────┘

Matrix representation in the basis \((|00\rangle, |01\rangle, |10\rangle, |11\rangle)\):

\[\begin{split}\text{SFE}(\theta) = \begin{bmatrix} 1 & 0 & 0 & 0 \\ 0 & \cos\theta & -\sin\theta & 0 \\ 0 & \sin\theta & \cos\theta & 0 \\ 0 & 0 & 0 & 1 \end{bmatrix}\end{split}\]

But, in contrast to SingleExcitationGate, this gate also keeps track of the number of 1’s between site p and site q. E.g., with three qubits and (p,q) = (0,2) it is identity outside the basis \((|001\rangle, |011\rangle, |100\rangle, |110\rangle)\), where it has matrix representation:

\[\begin{split}\text{SFE}(\theta) = \begin{bmatrix} \cos\theta & 0 & -\sin\theta & 0 \\ 0 & \cos\theta & 0 & \sin\theta \\ \sin\theta & 0 & \cos\theta & 0 \\ 0 & -\sin\theta & 0 & \cos\theta \end{bmatrix}\end{split}\]

I.e.,

\[\begin{split}\text{SFE}(\theta) = \begin{bmatrix} \cos\theta & -\sin\theta \\ \sin\theta & \cos\theta \end{bmatrix}\end{split}\]

in the \((|001\rangle, |100\rangle)\) basis and

\[\begin{split}\text{SFE}(\theta) = \begin{bmatrix} \cos\theta & \sin\theta \\ -\sin\theta & \cos\theta \end{bmatrix}\end{split}\]

in the \((|011\rangle, |110\rangle)\) basis, with opposite signs on sin since it has a 1 between p and q.

__init__(parameter: Parameter | ParameterExpression | float, creation_qubit_index: int, annihilation_qubit_index: int) → None

Initialize a single fermionic excitation evolution for two qubits with the given indices.

creation_qubit_index as \(p\), annihilation_qubit_index as \(q\), and parameter as \(\theta\).

Uses figure 8 in https://arxiv.org/pdf/2005.14475.

Parameters:

parameter (Parameter | ParameterExpression | float) – Parameter \(\theta\) determining the degree of single fermionic excitation evolution.
creation_qubit_index (int) – Index \(p\) of the qubit where a qubit excitation is partially added.
annihilation_qubit_index (int) – Index \(q\) of the qubit where a qubit excitation is partially removed.

Return type:

None

static active_qubits(gates: Iterable[Gate]) → set[int]

Return the active qubits in a sequence of gates.

Parameters:: gates (Iterable[Gate]) – Sequence of gates.
Return type:: set[int]

commutes_with_pauli_string(pauli_string: PauliString) → bool

Check if gate commutes with the given pauli string. Default is False.

The default implementation always returns False. So False is considered a safe answer. An only True should be trusted.

Parameters:: pauli_string (PauliString) – Pauli string to check commutation for.
Return type:: bool

classmethod decode(data: dict[str, Any]) → T

Decode a dictionary.

Parameters:: data (dict[str, Any]) – The dictionary representation.
Return type:: T

encode() → dict[str, Any]

Encode the instance into a dictionary.

Return type:: dict[str, Any]

flatten() → Iterator[Gate]

Flatten the gate into a list of primitive gates.

Return type:: Iterator[Gate]

property gates: list[Gate]

List of gates that the composite gate is constructed from.

The list of gates are the immediate sub-gates that the composite gate is constructed from, not necessarily the primitive gates. To expand the gate down to primitive gates use the primitive_gates property instead.

invert() → Self

Get the inverse of the gate.

Return type:: Self

is_fully_specified() → bool

Check if all parameters have been specified.

Return type:: bool

name: str

property parameters: list[float | Parameter | ParameterExpression]: List of all parameters available.

property qubit_indices: tuple[int, ...]: Indices of the qubits that gate is working on.

relocate(new_indices: Mapping[int, int]) → Self

Relocate the gate to new qubit indices.

Parameters:: new_indices (Mapping[int, int]) – Mapping between current qubit indices and new qubit indices.
Returns:: New gate with the qubit indices updated.
Return type:: Gate

static sorted_active_qubits(gates: Iterable[Gate]) → tuple[int, ...]

Return the active qubits in a sequence of gates, sorted, as a tuple.

Parameters:: gates (Iterable[Gate]) – Sequence of gates.
Return type:: tuple[int, …]

symbols(*, max_number_of_decimals: int | None = None) → list[str]

Symbols for represent the gate in a circuit.

Parameters:: max_number_of_decimals (int | None) – Maximum number of decimals to use for floats in the symbols. Defaults to None.
Return type:: list[str]

with_specified_parameters(parameter_value_pairs: dict[Parameter, float | ParameterExpression]) → Self

Assign parameters with the given float value.

Parameters:: parameter_value_pairs (dict[Parameter, float | ParameterExpression])
Return type:: Self

class ToffoliGate

Bases: CompositeGate, GateEncodingMixin

Toffoli gate, also known as Controlled-Controlled-X gate.

The Toffoli gate is a 3-qubit gate that flips the state of the target qubit if the state of the two control qubits are both in the state \(|1⟩\). The action of the Toffoli gate is given by:

\[\begin{split}\text{Toffoli} |011\rangle = |111\rangle, \\ \text{Toffoli} |111\rangle = |011\rangle,\end{split}\]

if qubit two is the target with qubits zero and one as controls, and the rest of the basis states are left unchanged.

Circuit form:

  ──■──
    │
  ──■──
  ┌─┴─┐
──┤ X ├──
  └───┘

\[\begin{split}\text{Toffoli} = \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 & 0 & 0 & 0 & 0 & 1 \\ 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 & 1 & 0 & 0 & 0 & 0 \\ \end{bmatrix}\end{split}\]

__init__(control_qubit_index_1: int, control_qubit_index_2: int, target_qubit_index: int) → None

Initialize a Toffoli gate.

Parameters:

control_qubit_index_1 (int) – Index of the first control qubit.
control_qubit_index_2 (int) – Index of the second control qubit.
target_qubit_index (int) – Index of the target qubit.

Return type:

None

static active_qubits(gates: Iterable[Gate]) → set[int]

Return the active qubits in a sequence of gates.

Parameters:: gates (Iterable[Gate]) – Sequence of gates.
Return type:: set[int]

commutes_with_pauli_string(pauli_string: PauliString) → bool

Check if gate commutes with the given pauli string. Default is False.

The default implementation always returns False. So False is considered a safe answer. An only True should be trusted.

Parameters:: pauli_string (PauliString) – Pauli string to check commutation for.
Return type:: bool

classmethod decode(data: dict[str, Any]) → T

Decode a dictionary.

Parameters:: data (dict[str, Any]) – The dictionary representation.
Return type:: T

encode() → dict[str, Any]

Encode the instance into a dictionary.

Return type:: dict[str, Any]

flatten() → Iterator[Gate]

Flatten the gate into a list of primitive gates.

Return type:: Iterator[Gate]

property gates: list[Gate]

List of gates that the composite gate is constructed from.

The list of gates are the immediate sub-gates that the composite gate is constructed from, not necessarily the primitive gates. To expand the gate down to primitive gates use the primitive_gates property instead.

invert() → Self

Get the inverse of the gate.

Return type:: Self

is_fully_specified() → bool

Check if all parameters have been specified.

Return type:: bool

name: str

property parameters: list[float | Parameter | ParameterExpression]: List of all parameters available.

property qubit_indices: tuple[int, ...]: Indices of the qubits that gate is working on.

relocate(new_indices: Mapping[int, int]) → Self

Relocate the gate to new qubit indices.

Parameters:: new_indices (Mapping[int, int]) – Mapping between current qubit indices and new qubit indices.
Returns:: New gate with the qubit indices updated.
Return type:: Gate

static sorted_active_qubits(gates: Iterable[Gate]) → tuple[int, ...]

Return the active qubits in a sequence of gates, sorted, as a tuple.

Parameters:: gates (Iterable[Gate]) – Sequence of gates.
Return type:: tuple[int, …]

symbols(*, max_number_of_decimals: int | None = None) → list[str]

Symbols for represent the gate in a circuit.

Parameters:: max_number_of_decimals (int | None) – Maximum number of decimals to use for floats in the symbols. Defaults to None.
Return type:: list[str]

with_specified_parameters(parameter_value_pairs: dict[Parameter, float | ParameterExpression]) → Self

Assign parameters with the given float value.

Parameters:: parameter_value_pairs (dict[Parameter, float | ParameterExpression])
Return type:: Self

class XGate

Bases: CompositeGate, GateEncodingMixin

Single qubit NOT- or X-gate.

The operator form of the X gate is the pauli X operator, and has the action.

\[\begin{split}X|0\rangle = |1\rangle, \\ X|1\rangle = |0\rangle.\end{split}\]

Circuit form:

  ┌───┐
──┤ X ├──
  └───┘

Matrix representation in the basis \((|0\rangle, |1\rangle)\):

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

__init__(qubit_index: int) → None

Initialize an X-gate for a qubit with the given index qubit_index.

Parameters:: qubit_index (int) – Index of the qubit for the X-gate to act on.
Return type:: None

static active_qubits(gates: Iterable[Gate]) → set[int]

Return the active qubits in a sequence of gates.

Parameters:: gates (Iterable[Gate]) – Sequence of gates.
Return type:: set[int]

commutes_with_pauli_string(pauli_string: PauliString) → bool

Check if gate commutes with the given pauli string. Default is False.

The default implementation always returns False. So False is considered a safe answer. An only True should be trusted.

Parameters:: pauli_string (PauliString) – Pauli string to check commutation for.
Return type:: bool

classmethod decode(data: dict[str, Any]) → T

Decode a dictionary.

Parameters:: data (dict[str, Any]) – The dictionary representation.
Return type:: T

encode() → dict[str, Any]

Encode the instance into a dictionary.

Return type:: dict[str, Any]

flatten() → Iterator[Gate]

Flatten the gate into a list of primitive gates.

Return type:: Iterator[Gate]

property gates: list[Gate]

List of gates that the composite gate is constructed from.

The list of gates are the immediate sub-gates that the composite gate is constructed from, not necessarily the primitive gates. To expand the gate down to primitive gates use the primitive_gates property instead.

invert() → Self

Get the inverse of the gate.

Return type:: Self

is_fully_specified() → bool

Check if all parameters have been specified.

Return type:: bool

name: str

property parameters: list[float | Parameter | ParameterExpression]: List of all parameters available.

property qubit_indices: tuple[int, ...]: Indices of the qubits that gate is working on.

relocate(new_indices: Mapping[int, int]) → Self

Relocate the gate to new qubit indices.

Parameters:: new_indices (Mapping[int, int]) – Mapping between current qubit indices and new qubit indices.
Returns:: New gate with the qubit indices updated.
Return type:: Gate

static sorted_active_qubits(gates: Iterable[Gate]) → tuple[int, ...]

Return the active qubits in a sequence of gates, sorted, as a tuple.

Parameters:: gates (Iterable[Gate]) – Sequence of gates.
Return type:: tuple[int, …]

symbols(*, max_number_of_decimals: int | None = None) → list[str]

Symbols for represent the gate in a circuit.

Parameters:: max_number_of_decimals (int | None) – Maximum number of decimals to use for floats in the symbols. Defaults to None.
Return type:: list[str]

with_specified_parameters(parameter_value_pairs: dict[Parameter, float | ParameterExpression]) → XGate

Assign parameters with the given float value. X gate has no parameters.

Parameters:: parameter_value_pairs (dict[Parameter, float | ParameterExpression])
Return type:: XGate

class XYGate

Bases: CompositeGate, GateEncodingMixin

Two qubit gate for creating an XX+YY interaction gate, also known as an XY-gate.

A two qubit gate for a parametrized rotation by \(\theta\) between \(|01\rangle\) and \(|01\rangle\) generated by the operator

\[e^{i\frac{\theta}{2} (X_i X_j + Y_i Y_j)}.\]

Circuit form:

  ┌──────────┐
──┤(XX+YY)(θ)├──
  └────┬─────┘
  ┌────┴─────┐
──┤(XX+YY)(θ)├──
  └──────────┘

Matrix representation in the basis \((|00\rangle, |01\rangle, |10\rangle, |11\rangle)\):

\[\begin{split}(\text{XX+YY})(\theta) = \begin{bmatrix} 1 & 0 & 0 & 0 \\ 0 & \cos\theta & i\sin\theta & 0 \\ 0 & i\sin\theta & \cos\theta & 0 \\ 0 & 0 & 0 & 1 \end{bmatrix}\end{split}\]

I.e., identity outside the basis \((|01\rangle, |10\rangle)\), where it has matrix representation:

\[\begin{split}(\text{XX+YY})(\theta) = \begin{bmatrix} \cos\theta & i\sin\theta \\ i\sin\theta & \cos\theta \\ \end{bmatrix}\end{split}\]

__init__(parameter: Parameter | ParameterExpression | float, index_1: int, index_2: int) → None

Initialize an (XX+YY)-gate for two qubits.

The indices are index_1 as i and index_2 as j.

Parameters:

parameter (Parameter | ParameterExpression | float) – Parameter \(\theta\) determining the degree of rotation.
index_1 (int) – Index of one of the qubits where a qubit excitation is partially added or removed.
index_2 (int) – Index of the other qubit where a qubit excitation is partially added or removed.

Return type:

None

static active_qubits(gates: Iterable[Gate]) → set[int]

Return the active qubits in a sequence of gates.

Parameters:: gates (Iterable[Gate]) – Sequence of gates.
Return type:: set[int]

commutes_with_pauli_string(pauli_string: PauliString) → bool

Check if gate commutes with the given pauli string. Default is False.

The default implementation always returns False. So False is considered a safe answer. An only True should be trusted.

Parameters:: pauli_string (PauliString) – Pauli string to check commutation for.
Return type:: bool

classmethod decode(data: dict[str, Any]) → T

Decode a dictionary.

Parameters:: data (dict[str, Any]) – The dictionary representation.
Return type:: T

encode() → dict[str, Any]

Encode the instance into a dictionary.

Return type:: dict[str, Any]

flatten() → Iterator[Gate]

Flatten the gate into a list of primitive gates.

Return type:: Iterator[Gate]

property gates: list[Gate]

List of gates that the composite gate is constructed from.

The list of gates are the immediate sub-gates that the composite gate is constructed from, not necessarily the primitive gates. To expand the gate down to primitive gates use the primitive_gates property instead.

invert() → Self

Get the inverse of the gate.

Return type:: Self

is_fully_specified() → bool

Check if all parameters have been specified.

Return type:: bool

name: str

property parameters: list[float | Parameter | ParameterExpression]: List of all parameters available.

property qubit_indices: tuple[int, ...]: Indices of the qubits that gate is working on.

relocate(new_indices: Mapping[int, int]) → Self

Relocate the gate to new qubit indices.

Parameters:: new_indices (Mapping[int, int]) – Mapping between current qubit indices and new qubit indices.
Returns:: New gate with the qubit indices updated.
Return type:: Gate

static sorted_active_qubits(gates: Iterable[Gate]) → tuple[int, ...]

Return the active qubits in a sequence of gates, sorted, as a tuple.

Parameters:: gates (Iterable[Gate]) – Sequence of gates.
Return type:: tuple[int, …]

symbols(*, max_number_of_decimals: int | None = None) → list[str]

Symbols for represent the gate in a circuit.

Parameters:: max_number_of_decimals (int | None) – Maximum number of decimals to use for floats in the symbols. Defaults to None.
Return type:: list[str]

with_specified_parameters(parameter_value_pairs: dict[Parameter, float | ParameterExpression]) → Self

Assign parameters with the given float value.

Parameters:: parameter_value_pairs (dict[Parameter, float | ParameterExpression])
Return type:: Self

class YGate

Bases: CompositeGate, GateEncodingMixin

Single qubit Y-gate.

The operator form of the Y gate is the pauli Y operator, and has the action.

\[\begin{split}Y|0\rangle = i|1\rangle, \\ Y|1\rangle = -i|0\rangle.\end{split}\]

Circuit form:

  ┌───┐
──┤ Y ├──
  └───┘

Matrix representation in the basis \((|0\rangle, |1\rangle)\):

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

__init__(qubit_index: int) → None

Initialize an Y-gate for a qubit with the given index qubit_index.

Parameters:: qubit_index (int) – Index of the qubit for the Y-gate to act on.
Return type:: None

static active_qubits(gates: Iterable[Gate]) → set[int]

Return the active qubits in a sequence of gates.

Parameters:: gates (Iterable[Gate]) – Sequence of gates.
Return type:: set[int]

commutes_with_pauli_string(pauli_string: PauliString) → bool

Check if gate commutes with the given pauli string. Default is False.

The default implementation always returns False. So False is considered a safe answer. An only True should be trusted.

Parameters:: pauli_string (PauliString) – Pauli string to check commutation for.
Return type:: bool

classmethod decode(data: dict[str, Any]) → T

Decode a dictionary.

Parameters:: data (dict[str, Any]) – The dictionary representation.
Return type:: T

encode() → dict[str, Any]

Encode the instance into a dictionary.

Return type:: dict[str, Any]

flatten() → Iterator[Gate]

Flatten the gate into a list of primitive gates.

Return type:: Iterator[Gate]

property gates: list[Gate]

List of gates that the composite gate is constructed from.

The list of gates are the immediate sub-gates that the composite gate is constructed from, not necessarily the primitive gates. To expand the gate down to primitive gates use the primitive_gates property instead.

invert() → Self

Get the inverse of the gate.

Return type:: Self

is_fully_specified() → bool

Check if all parameters have been specified.

Return type:: bool

name: str

property parameters: list[float | Parameter | ParameterExpression]: List of all parameters available.

property qubit_indices: tuple[int, ...]: Indices of the qubits that gate is working on.

relocate(new_indices: Mapping[int, int]) → Self

Relocate the gate to new qubit indices.

Parameters:: new_indices (Mapping[int, int]) – Mapping between current qubit indices and new qubit indices.
Returns:: New gate with the qubit indices updated.
Return type:: Gate

static sorted_active_qubits(gates: Iterable[Gate]) → tuple[int, ...]

Return the active qubits in a sequence of gates, sorted, as a tuple.

Parameters:: gates (Iterable[Gate]) – Sequence of gates.
Return type:: tuple[int, …]

symbols(*, max_number_of_decimals: int | None = None) → list[str]

Symbols for represent the gate in a circuit.

Parameters:: max_number_of_decimals (int | None) – Maximum number of decimals to use for floats in the symbols. Defaults to None.
Return type:: list[str]

with_specified_parameters(parameter_value_pairs: dict[Parameter, float | ParameterExpression]) → Self

Assign parameters with the given float value.

Parameters:: parameter_value_pairs (dict[Parameter, float | ParameterExpression])
Return type:: Self

class ZGate

Bases: CompositeGate, GateEncodingMixin

Single qubit Z-gate.

The operator form of the Z gate is the pauli Z operator, and has the action.

\[\begin{split}Z|0\rangle = |0\rangle, \\ Z|1\rangle = -|1\rangle.\end{split}\]

Circuit form:

  ┌───┐
──┤ Z ├──
  └───┘

Matrix representation in the basis \((|0\rangle, |1\rangle)\):

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

__init__(qubit_index: int) → None

Initialize a Z-gate for a qubit with the given index qubit_index.

Parameters:: qubit_index (int) – Index of the qubit for the Z-gate to act on.
Return type:: None

static active_qubits(gates: Iterable[Gate]) → set[int]

Return the active qubits in a sequence of gates.

Parameters:: gates (Iterable[Gate]) – Sequence of gates.
Return type:: set[int]

commutes_with_pauli_string(pauli_string: PauliString) → bool

Check if gate commutes with the given pauli string. Default is False.

The default implementation always returns False. So False is considered a safe answer. An only True should be trusted.

Parameters:: pauli_string (PauliString) – Pauli string to check commutation for.
Return type:: bool

classmethod decode(data: dict[str, Any]) → T

Decode a dictionary.

Parameters:: data (dict[str, Any]) – The dictionary representation.
Return type:: T

encode() → dict[str, Any]

Encode the instance into a dictionary.

Return type:: dict[str, Any]

flatten() → Iterator[Gate]

Flatten the gate into a list of primitive gates.

Return type:: Iterator[Gate]

property gates: list[Gate]

List of gates that the composite gate is constructed from.

The list of gates are the immediate sub-gates that the composite gate is constructed from, not necessarily the primitive gates. To expand the gate down to primitive gates use the primitive_gates property instead.

invert() → Self

Get the inverse of the gate.

Return type:: Self

is_fully_specified() → bool

Check if all parameters have been specified.

Return type:: bool

name: str

property parameters: list[float | Parameter | ParameterExpression]: List of all parameters available.

property qubit_indices: tuple[int, ...]: Indices of the qubits that gate is working on.

relocate(new_indices: Mapping[int, int]) → Self

Relocate the gate to new qubit indices.

Parameters:: new_indices (Mapping[int, int]) – Mapping between current qubit indices and new qubit indices.
Returns:: New gate with the qubit indices updated.
Return type:: Gate

static sorted_active_qubits(gates: Iterable[Gate]) → tuple[int, ...]

Return the active qubits in a sequence of gates, sorted, as a tuple.

Parameters:: gates (Iterable[Gate]) – Sequence of gates.
Return type:: tuple[int, …]

symbols(*, max_number_of_decimals: int | None = None) → list[str]

Symbols for represent the gate in a circuit.

Parameters:: max_number_of_decimals (int | None) – Maximum number of decimals to use for floats in the symbols. Defaults to None.
Return type:: list[str]

with_specified_parameters(parameter_value_pairs: dict[Parameter, float | ParameterExpression]) → Self

Assign parameters with the given float value.

Parameters:: parameter_value_pairs (dict[Parameter, float | ParameterExpression])
Return type:: Self

combine_gates(name: str, gates: Iterable[Gate], *, num_qubits: int | None = None) → GateFactory

Combine a sequence of gates into a single composite gate.

Creates a function that takes qubit indices as input, maps the gates to the new qubit indices, and creates a new composite gate from the result.

If num_qubits is provided, the new gate will have that number of qubits. Otherwise, the number of qubits is inferred from the gates.

Parameters:

name (str) – The name of the new gate.
gates (Iterable[Gate]) – Sequence of gates.
num_qubits (int | None) – The number of qubits the new gate should act on. If None, the number of qubits is inferred from the gates.

Returns:

A composite gate representing the combined gates.

Return type:

GateFactory

compact_qubits(gates: Iterable[Gate]) → list[Gate]

Re-index the qubits in gates to be consecutive.

Parameters:: gates (Iterable[Gate]) – Sequence of gates.
Returns:: Gates where the qubits are re-indexed to be consecutive.
Return type:: list[Gate]

composite_gate(fn: Callable[[P], Iterator[Gate]], /) → Callable[[P], CompositeGate]

composite_gate(*, symbols: list[str] | None = None, qubit_indices: tuple[int, ...] | None = None) → Callable[[Callable[[P], Iterator[Gate]]], Callable[[P], CompositeGate]]

Create a composite gate from a function that generates a sequence of gates.

Parameters:

fn (Callable[[~P], Iterator[Gate]] | None) – Function that generates a sequence of gates.
symbols (list[str] | None) – List of symbols for the gate parameters.
qubit_indices (tuple[int, ...] | None) – Tuple of qubit indices for the gate.

Returns:

A function that generates a composite gate.

Return type:

Callable[[~P], CompositeGate] | Callable[[Callable[[~P], Iterator[Gate]]], Callable[[~P], CompositeGate]]

relocate_gates(gates: Iterable[Gate], qubit_map: Mapping[int, int]) → Iterator[Gate]

Relocate a sequence of gates by mapping qubit indices according to a given qubit map.

Parameters:

gates (Iterable[Gate]) – Sequence of gates to relocate.
qubit_map (Mapping[int, int]) – Mapping between current qubit indices and new qubit indices.

Return type:

Iterator[Gate]