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.
`DoubleFermionicEvolutionGate`	Four qubit gate for the Hermitian time evolution of a double fermionic excitation term.
`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.
`PauliGate`	General Pauli exponential gate.
`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.
`SingleFermionicEvolutionGate`	Two qubit gate for the Hermitian time evolution of a single fermionic hopping term.
`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.
`XXplusYYGate`	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() → list[Gate]

Flatten the gate into a list of primitive gates.

Return type:: list[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

metadata_hash(*, max_number_of_decimals: int = 6) → tuple[object, ...]

Return a hashable representation of the gate for metadata caching.

Parameters:: max_number_of_decimals (int) – Maximum number of decimals for rounding float parameters.
Return type:: tuple[object, …]

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() → list[Gate]

Flatten the gate into a list of primitive gates.

Return type:: list[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

metadata_hash(*, max_number_of_decimals: int = 6) → tuple[object, ...]

Return a hashable representation of the gate for metadata caching.

Parameters:: max_number_of_decimals (int) – Maximum number of decimals for rounding float parameters.
Return type:: tuple[object, …]

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]

property annihilation_index_1: int: The first qubit index where an excitation is (partially) annihilated (\(r\)).

property annihilation_index_2: int: The second qubit index where an excitation is (partially) annihilated (\(s\)).

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

property creation_index_1: int: The first qubit index where an excitation is (partially) created (\(p\)).

property creation_index_2: int: The second qubit index where an excitation is (partially) created (\(q\)).

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() → list[Gate]

Flatten the gate into a list of primitive gates.

Return type:: list[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

metadata_hash(*, max_number_of_decimals: int = 6) → tuple[object, ...]

Return a hashable representation of the gate for metadata caching.

Parameters:: max_number_of_decimals (int) – Maximum number of decimals for rounding float parameters.
Return type:: tuple[object, …]

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 DoubleFermionicEvolutionGate

Bases: CompositeGate, GateEncodingMixin

Four qubit gate for the Hermitian time evolution of a double fermionic excitation term.

This gate implements the unitary generated by the Hermitian operator

\[H_{pqrs} = a_p^\dagger a_q^\dagger a_r a_s + a_s^\dagger a_r^\dagger a_q a_p,\]

namely \(U(\theta) = e^{-i \theta H_{pqrs}}\), including the Jordan-Wigner \(Z\)-strings. Here \(a_i\) and \(a_i^\dagger\) denote fermionic annihilation and creation operators at the \(i\)’th site.

In contrast to DoubleFermionicExcitationGate – whose anti-Hermitian generator produces a real rotation suited to variational ansaetze – this gate performs genuine Hamiltonian time evolution, as needed by randomized product formulas such as qDRIFT.

The conjugation by SGate on the first creation qubit converts the anti-Hermitian ansatz rotation into Hermitian time evolution, giving \(e^{-i\theta H_{pqrs}} = S_p \, \mathrm{DFE}(-\theta) \, S_p^\dagger\), i.e. the DoubleFermionicExcitationGate conjugated by an SGate on the first creation qubit.

Circuit form:

  ┌─────────┐
──┤DFEvo1(θ)├──
  └────┬────┘
  ┌────┴────┐
──┤DFEvo2(θ)├──
  └────┬────┘
  ┌────┴────┐
──┤DFEvo3(θ)├──
  └────┬────┘
  ┌────┴────┐
──┤DFEvo4(θ)├──
  └─────────┘

Identity outside the basis \((|0011\rangle, |1100\rangle)\) (up to the Jordan-Wigner sign), where it has matrix representation:

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

(Compare with DoubleFermionicExcitationGate.)

__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 time-evolution gate for four 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, and parameter as \(\theta\).

Parameters:

parameter (Parameter | ParameterExpression | float) – Parameter \(\theta\) determining the evolution time of the two-body term.
creation_qubit_index_1 (int) – Index \(p\) of the first qubit where a fermionic excitation is potentially added.
creation_qubit_index_2 (int) – Index \(q\) of the second qubit where a fermionic excitation is potentially added.
annihilation_qubit_index_1 (int) – Index \(r\) of the first qubit where a fermionic excitation is potentially removed.
annihilation_qubit_index_2 (int) – Index \(s\) of the second qubit where a fermionic 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]

property annihilation_index_1: int: The first qubit index where an excitation is (partially) annihilated (\(r\)).

property annihilation_index_2: int: The second qubit index where an excitation is (partially) annihilated (\(s\)).

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

property creation_index_1: int: The first qubit index where an excitation is (partially) created (\(p\)).

property creation_index_2: int: The second qubit index where an excitation is (partially) created (\(q\)).

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() → list[Gate]

Flatten the gate into a list of primitive gates.

Return type:: list[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

metadata_hash(*, max_number_of_decimals: int = 6) → tuple[object, ...]

Return a hashable representation of the gate for metadata caching.

Parameters:: max_number_of_decimals (int) – Maximum number of decimals for rounding float parameters.
Return type:: tuple[object, …]

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

property annihilation_index_1: int: The first qubit index where an excitation is (partially) annihilated (\(r\)).

property annihilation_index_2: int: The second qubit index where an excitation is (partially) annihilated (\(s\)).

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

property creation_index_1: int: The first qubit index where an excitation is (partially) created (\(p\)).

property creation_index_2: int: The second qubit index where an excitation is (partially) created (\(q\)).

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() → list[Gate]

Flatten the gate into a list of primitive gates.

Return type:: list[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

metadata_hash(*, max_number_of_decimals: int = 6) → tuple[object, ...]

Return a hashable representation of the gate for metadata caching.

Parameters:: max_number_of_decimals (int) – Maximum number of decimals for rounding float parameters.
Return type:: tuple[object, …]

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() → list[Gate]

Flatten the gate into a list of primitive gates.

Return type:: list[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

metadata_hash(*, max_number_of_decimals: int = 6) → tuple[object, ...]

Return a hashable representation of the gate for metadata caching.

Parameters:: max_number_of_decimals (int) – Maximum number of decimals for rounding float parameters.
Return type:: tuple[object, …]

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() → list[Gate]

Flatten the gate into a list of primitive gates.

Return type:: list[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

metadata_hash(*, max_number_of_decimals: int = 6) → tuple[object, ...]

Return a hashable representation of the gate for metadata caching.

Parameters:: max_number_of_decimals (int) – Maximum number of decimals for rounding float parameters.
Return type:: tuple[object, …]

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 PauliGate

Bases: CompositeGate, GateEncodingMixin

General Pauli exponential gate.

Implements the unitary \(e^{-i\theta P}\) for an arbitrary Pauli string \(P\).

The decomposition uses the standard basis-change / parity-ladder construction:

Basis change – rotate each non-Z qubit into the Z basis: X-qubits are conjugated with HGate; Y-qubits are conjugated with SdgGate followed by HGate.
Parity ladder – accumulate the parity of all participating qubits onto the last one via a sequence of CXGate.
Central rotation – apply RZGate (2 * theta) on the last qubit.
Inverse parity ladder – reverse the CXGate sequence.
Inverse basis change – undo the initial rotations.

__init__(parameter: Parameter | ParameterExpression | float, pauli_string: PauliString) → None

Initialize a Pauli exponential gate.

Parameters:

parameter (Parameter | ParameterExpression | float) – Parameter \(\theta\) determining the rotation angle.
pauli_string (PauliString) – The Pauli operator to exponentiate.

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]) → PauliGate

Decode a dictionary.

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

encode() → dict[str, Any]

Encode the instance into a dictionary.

Return type:: dict[str, Any]

flatten() → list[Gate]

Flatten the gate into a list of primitive gates.

Return type:: list[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

metadata_hash(*, max_number_of_decimals: int = 6) → tuple[object, ...]

Return a hashable representation of the gate for metadata caching.

Parameters:: max_number_of_decimals (int) – Maximum number of decimals for rounding float parameters.
Return type:: tuple[object, …]

name: str

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

property pauli_string: PauliString: The Pauli string that is exponentiated by the gate.

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

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

Relocate the gate to new qubit indices, including the Pauli string.

Parameters:: new_indices (Mapping[int, int]) – Mapping from current qubit indices to new qubit indices.
Return type:: PauliGate

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 to 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() → list[Gate]

Flatten the gate into a list of primitive gates.

Return type:: list[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

metadata_hash(*, max_number_of_decimals: int = 6) → tuple[object, ...]

Return a hashable representation of the gate for metadata caching.

Parameters:: max_number_of_decimals (int) – Maximum number of decimals for rounding float parameters.
Return type:: tuple[object, …]

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() → list[Gate]

Flatten the gate into a list of primitive gates.

Return type:: list[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

metadata_hash(*, max_number_of_decimals: int = 6) → tuple[object, ...]

Return a hashable representation of the gate for metadata caching.

Parameters:: max_number_of_decimals (int) – Maximum number of decimals for rounding float parameters.
Return type:: tuple[object, …]

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() → list[Gate]

Flatten the gate into a list of primitive gates.

Return type:: list[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

metadata_hash(*, max_number_of_decimals: int = 6) → tuple[object, ...]

Return a hashable representation of the gate for metadata caching.

Parameters:: max_number_of_decimals (int) – Maximum number of decimals for rounding float parameters.
Return type:: tuple[object, …]

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]

property annihilation_index: int: The qubit index where an excitation is (partially) annihilated.

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

property creation_index: int: The qubit index where an excitation is (partially) created.

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() → list[Gate]

Flatten the gate into a list of primitive gates.

Return type:: list[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

metadata_hash(*, max_number_of_decimals: int = 6) → tuple[object, ...]

Return a hashable representation of the gate for metadata caching.

Parameters:: max_number_of_decimals (int) – Maximum number of decimals for rounding float parameters.
Return type:: tuple[object, …]

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 SingleFermionicEvolutionGate

Bases: CompositeGate, GateEncodingMixin

Two qubit gate for the Hermitian time evolution of a single fermionic hopping term.

This gate implements the unitary generated by the Hermitian operator

\[H_{pq} = a_p^\dagger a_q + a_q^\dagger a_p,\]

namely \(U(\theta) = e^{-i \theta H_{pq}}\), including the Jordan-Wigner \(Z\)-string on the qubits between p and q. Here \(a_i\) and \(a_i^\dagger\) denote fermionic annihilation and creation operators at the \(i\)’th site.

In contrast to SingleFermionicExcitationGate – whose anti-Hermitian generator \(a_p^\dagger a_q - a_q^\dagger a_p\) produces a real Givens rotation suited to variational ansaetze – this gate performs genuine Hamiltonian time evolution, as needed by randomized product formulas such as qDRIFT.

The conjugation by SGate maps the anti-Hermitian ansatz generator \(a_p^\dagger a_q - a_q^\dagger a_p\) to \(-i\) times the Hermitian generator \(H_{pq}\), so that \(e^{-i\theta H_{pq}} = S_p \, \mathrm{SFE}(\theta) \, S_p^\dagger\), i.e. the SingleFermionicExcitationGate conjugated by an SGate on the creation qubit.

Circuit form:

  ┌─────────┐
──┤SFEvo1(θ)├──
  └────┬────┘
  ┌────┴────┐
──┤SFEvo2(θ)├──
  └─────────┘

Identity outside the basis \((|01\rangle, |10\rangle)\) (up to the Jordan-Wigner sign for the qubits between p and q), where it has matrix representation:

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

(Compare with SingleFermionicExcitationGate and XXplusYYGate.)

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

Initialize a single fermionic time-evolution gate 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 evolution time of the hopping term.
creation_qubit_index (int) – Index \(p\) of the qubit where a fermionic excitation is partially added.
annihilation_qubit_index (int) – Index \(q\) of the qubit where a fermionic 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]

property annihilation_index: int: The qubit index where a fermionic excitation is (partially) annihilated.

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

property creation_index: int: The qubit index where a fermionic excitation is (partially) created.

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() → list[Gate]

Flatten the gate into a list of primitive gates.

Return type:: list[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

metadata_hash(*, max_number_of_decimals: int = 6) → tuple[object, ...]

Return a hashable representation of the gate for metadata caching.

Parameters:: max_number_of_decimals (int) – Maximum number of decimals for rounding float parameters.
Return type:: tuple[object, …]

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

property annihilation_index: int: The qubit index where an excitation is (partially) annihilated.

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

property creation_index: int: The qubit index where an excitation is (partially) created.

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() → list[Gate]

Flatten the gate into a list of primitive gates.

Return type:: list[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

metadata_hash(*, max_number_of_decimals: int = 6) → tuple[object, ...]

Return a hashable representation of the gate for metadata caching.

Parameters:: max_number_of_decimals (int) – Maximum number of decimals for rounding float parameters.
Return type:: tuple[object, …]

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() → list[Gate]

Flatten the gate into a list of primitive gates.

Return type:: list[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

metadata_hash(*, max_number_of_decimals: int = 6) → tuple[object, ...]

Return a hashable representation of the gate for metadata caching.

Parameters:: max_number_of_decimals (int) – Maximum number of decimals for rounding float parameters.
Return type:: tuple[object, …]

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() → list[Gate]

Flatten the gate into a list of primitive gates.

Return type:: list[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

metadata_hash(*, max_number_of_decimals: int = 6) → tuple[object, ...]

Return a hashable representation of the gate for metadata caching.

Parameters:: max_number_of_decimals (int) – Maximum number of decimals for rounding float parameters.
Return type:: tuple[object, …]

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 XXplusYYGate

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() → list[Gate]

Flatten the gate into a list of primitive gates.

Return type:: list[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

metadata_hash(*, max_number_of_decimals: int = 6) → tuple[object, ...]

Return a hashable representation of the gate for metadata caching.

Parameters:: max_number_of_decimals (int) – Maximum number of decimals for rounding float parameters.
Return type:: tuple[object, …]

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() → list[Gate]

Flatten the gate into a list of primitive gates.

Return type:: list[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

metadata_hash(*, max_number_of_decimals: int = 6) → tuple[object, ...]

Return a hashable representation of the gate for metadata caching.

Parameters:: max_number_of_decimals (int) – Maximum number of decimals for rounding float parameters.
Return type:: tuple[object, …]

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() → list[Gate]

Flatten the gate into a list of primitive gates.

Return type:: list[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

metadata_hash(*, max_number_of_decimals: int = 6) → tuple[object, ...]

Return a hashable representation of the gate for metadata caching.

Parameters:: max_number_of_decimals (int) – Maximum number of decimals for rounding float parameters.
Return type:: tuple[object, …]

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]