paddle_quantum.ansatz.circuit

The source file of the Circuit class.

class paddle_quantum.ansatz.circuit.Circuit(num_qubits=None)

Bases: Sequential

Quantum circuit.

Parameters:

num_qubits (int | None) – Number of qubits. Defaults to None.

property isdynamic: bool

Whether the circuit is dynamic

property num_qubits: int

Number of qubits.

property param: Tensor

Flattened parameters in the circuit.

property grad: ndarray

Gradients with respect to the flattened parameters.

update_param(theta, idx=None)

Replace parameters of all/one layer(s) by theta.

Parameters:

• theta (Tensor | ndarray | float) – New parameters

• idx (int | None) – Index of replacement. Defaults to None, referring to all layers.

transfer_static()

set stop_gradient of all parameters of the circuit as True

randomize_param(arg0=0, arg1=6.283185307179586, initializer_type='Uniform')

Randomize parameters of the circuit based on the initializer. Current we only support Uniform and Normal initializer.

A detail introduction can be found in https://www.paddlepaddle.org.cn/documentation/docs/zh/api/paddle/nn/initializer/Uniform_en.html

Parameters:

• arg0 (float) – first argument of the initializer. Defaults to 0.

• arg1 (float) – first argument of the initializer. Defaults to 2 * pi.

• initializer_type (str) – The type of the initializer. Defaults to ‘Uniform’.

h(qubits_idx='full', depth=1)

Add single-qubit Hadamard gates.

The matrix form of such a gate is:

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

Parameters:

• qubits_idx (Iterable[int] | int | str) – Indices of the qubits on which the gates are applied. Defaults to ‘full’.

• depth (int) – Number of layers. Defaults to 1.

s(qubits_idx='full', depth=1)

Add single-qubit S gates.

The matrix form of such a gate is:

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

Parameters:

• qubits_idx (Iterable[int] | int | str) – Indices of the qubits on which the gates are applied. Defaults to ‘full’.

• depth (int) – Number of layers. Defaults to 1.

sdg(qubits_idx='full', depth=1)

Add single-qubit S dagger (S inverse) gates.

The matrix form of such a gate is:

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

Parameters:

• qubits_idx (Iterable[int] | int | str) – Indices of the qubits on which the gates are applied. Defaults to 'full'.

• depth (int) – Number of layers. Defaults to 1.

t(qubits_idx='full', depth=1)

Add single-qubit T gates.

The matrix form of such a gate is:

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

Parameters:

• qubits_idx (Iterable[int] | int | str) – Indices of the qubits on which the gates are applied. Defaults to ‘full’.

• depth (int) – Number of layers. Defaults to 1.

tdg(qubits_idx='full', depth=1)

Add single-qubit T dagger (T inverse) gates.

The matrix form of such a gate is:

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

Parameters:

• qubits_idx (Iterable[int] | int | str) – Indices of the qubits on which the gates are applied. Defaults to 'full'.

• depth (int) – Number of layers. Defaults to 1.

x(qubits_idx='full', depth=1)

Add single-qubit X gates.

The matrix form of such a gate is:

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

Parameters:

• qubits_idx (Iterable[int] | int | str) – Indices of the qubits on which the gates are applied. Defaults to ‘full’.

• depth (int) – Number of layers. Defaults to 1.

y(qubits_idx='full', depth=1)

Add single-qubit Y gates.

The matrix form of such a gate is:

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

Parameters:

• qubits_idx (Iterable[int] | int | str) – Indices of the qubits on which the gates are applied. Defaults to ‘full’.

• depth (int) – Number of layers. Defaults to 1.

z(qubits_idx='full', depth=1)

Add single-qubit Z gates.

The matrix form of such a gate is:

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

Parameters:

• qubits_idx (Iterable[int] | int | str) – Indices of the qubits on which the gates are applied. Defaults to ‘full’.

• depth (int) – Number of layers. Defaults to 1.

p(qubits_idx='full', depth=1, param=None, param_sharing=False)

Add single-qubit P gates.

The matrix form of such a gate is:

\[\begin{split}P(\theta) = \begin{bmatrix} 1 & 0 \\ 0 & e^{i\theta} \end{bmatrix}\end{split}\]

Parameters:

• qubits_idx (Iterable[int] | int | str) – Indices of the qubits on which the gates are applied. Defaults to ‘full’.

• depth (int) – Number of layers. Defaults to 1.

• param (Tensor | float | None) – Parameters of the gates. Defaults to None.

• param_sharing (bool) – Whether gates in the same layer share a parameter. Defaults to False.

rx(qubits_idx='full', depth=1, param=None, param_sharing=False)

Add single-qubit rotation gates about the x-axis.

The matrix form of such a gate is:

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

Parameters:

• qubits_idx (Iterable[int] | int | str) – Indices of the qubits on which the gates are applied. Defaults to ‘full’.

• depth (int) – Number of layers. Defaults to 1.

• param (Tensor | float | None) – Parameters of the gates. Defaults to None.

• param_sharing (bool) – Whether gates in the same layer share a parameter. Defaults to False.

ry(qubits_idx='full', depth=1, param=None, param_sharing=False)

Add single-qubit rotation gates about the y-axis.

The matrix form of such a gate is:

\[\begin{split}R_Y(\theta) = \begin{bmatrix} \cos\frac{\theta}{2} & -\sin\frac{\theta}{2} \\ \sin\frac{\theta}{2} & \cos\frac{\theta}{2} \end{bmatrix}\end{split}\]

Parameters:

• qubits_idx (Iterable[int] | int | str) – Indices of the qubits on which the gates are applied. Defaults to ‘full’.

• depth (int) – Number of layers. Defaults to 1.

• param (Tensor | float | None) – Parameters of the gates. Defaults to None.

• param_sharing (bool) – Whether gates in the same layer share a parameter. Defaults to False.

rz(qubits_idx='full', depth=1, param=None, param_sharing=False)

Add single-qubit rotation gates about the z-axis.

The matrix form of such a gate is:

\[\begin{split}R_Z(\theta) = \begin{bmatrix} e^{-i\frac{\theta}{2}} & 0 \\ 0 & e^{i\frac{\theta}{2}} \end{bmatrix}\end{split}\]

Parameters:

• qubits_idx (Iterable[int] | int | str) – Indices of the qubits on which the gates are applied. Defaults to ‘full’.

• depth (int) – Number of layers. Defaults to 1.

• param (Tensor | float | None) – Parameters of the gates. Defaults to None.

• param_sharing (bool) – Whether gates in the same layer share a parameter. Defaults to False.

u3(qubits_idx='full', depth=1, param=None, param_sharing=False)

Add single-qubit rotation gates.

The matrix form of such a gate is:

\[\begin{split}\begin{align} U_3(\theta, \phi, \lambda) = \begin{bmatrix} \cos\frac\theta2&-e^{i\lambda}\sin\frac\theta2\\ e^{i\phi}\sin\frac\theta2&e^{i(\phi+\lambda)}\cos\frac\theta2 \end{bmatrix} \end{align}\end{split}\]

Parameters:

• qubits_idx (Iterable[int] | int | str) – Indices of the qubits on which the gates are applied. Defaults to ‘full’.

• depth (int) – Number of layers. Defaults to 1.

• param (Tensor | Iterable[float] | None) – Parameters of the gates. Defaults to None.

• param_sharing (bool) – Whether gates in the same layer share a parameter. Defaults to False.

cnot(qubits_idx='cycle', depth=1)

Add CNOT gates.

For a 2-qubit quantum circuit, when qubits_idx is [0, 1], the matrix form of such a gate is:

\[\begin{split}\begin{align} \mathit{CNOT} &=|0\rangle \langle 0|\otimes I + |1 \rangle \langle 1|\otimes X\\ &= \begin{bmatrix} 1 & 0 & 0 & 0 \\ 0 & 1 & 0 & 0 \\ 0 & 0 & 0 & 1 \\ 0 & 0 & 1 & 0 \end{bmatrix} \end{align}\end{split}\]

Parameters:

• qubits_idx (Iterable[int] | str) – Indices of the qubits on which the gates are applied. Defaults to ‘cycle’.

• depth (int) – Number of layers. Defaults to 1.

cy(qubits_idx='cycle', depth=1)

Add controlled Y gates.

For a 2-qubit quantum circuit, when qubits_idx is [0, 1], the matrix form of such a gate is:

\[\begin{split}\begin{align} \mathit{CY} &=|0\rangle \langle 0|\otimes I + |1 \rangle \langle 1|\otimes Y\\ &= \begin{bmatrix} 1 & 0 & 0 & 0 \\ 0 & 1 & 0 & 0 \\ 0 & 0 & 0 & -1j \\ 0 & 0 & 1j & 0 \end{bmatrix} \end{align}\end{split}\]

Parameters:

• qubits_idx (Iterable[int] | str) – Indices of the qubits on which the gates are applied. Defaults to ‘cycle’.

• depth (int) – Number of layers. Defaults to 1.

cz(qubits_idx='linear', depth=1)

Add controlled Z gates.

For a 2-qubit quantum circuit, when qubits_idx is [0, 1], the matrix form of such a gate is:

\[\begin{split}\begin{align} \mathit{CZ} &=|0\rangle \langle 0|\otimes I + |1 \rangle \langle 1|\otimes Z\\ &= \begin{bmatrix} 1 & 0 & 0 & 0 \\ 0 & 1 & 0 & 0 \\ 0 & 0 & 1 & 0 \\ 0 & 0 & 0 & -1 \end{bmatrix} \end{align}\end{split}\]

Parameters:

• qubits_idx (Iterable[int] | str) – Indices of the qubits on which the gates are applied. Defaults to ‘linear’.

• depth (int) – Number of layers. Defaults to 1.

swap(qubits_idx='linear', depth=1)

Add SWAP gates.

The matrix form of such a gate is:

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

Parameters:

• qubits_idx (Iterable[int] | str) – Indices of the qubits on which the gates are applied. Defaults to ‘linear’.

• depth (int) – Number of layers. Defaults to 1.

cp(qubits_idx='cycle', depth=1, param=None, param_sharing=False)

Add controlled P gates.

For a 2-qubit quantum circuit, when qubits_idx is [0, 1], the matrix form of such a gate is:

\[\begin{split}\begin{align} \mathit{CP}(\theta) = \begin{bmatrix} 1 & 0 & 0 & 0 \\ 0 & 1 & 0 & 0 \\ 0 & 0 & 1 & 0 \\ 0 & 0 & 0 & e^{i\theta} \end{bmatrix} \end{align}\end{split}\]

Parameters:

• qubits_idx (Iterable[int] | str) – Indices of the qubits on which the gates are applied. Defaults to ‘cycle’.

• depth (int) – Number of layers. Defaults to 1.

• param (Tensor | float | None) – Parameters of the gates. Defaults to None.

• param_sharing (bool) – Whether gates in the same layer share a parameter. Defaults to False.

crx(qubits_idx='cycle', depth=1, param=None, param_sharing=False)

Add controlled rotation gates about the x-axis.

For a 2-qubit quantum circuit, when qubits_idx is [0, 1], the matrix form of such a gate is:

\[\begin{split}\begin{align} \mathit{CR_X} &=|0\rangle \langle 0|\otimes I + |1 \rangle \langle 1|\otimes R_X\\ &= \begin{bmatrix} 1 & 0 & 0 & 0 \\ 0 & 1 & 0 & 0 \\ 0 & 0 & \cos\frac{\theta}{2} & -i\sin\frac{\theta}{2} \\ 0 & 0 & -i\sin\frac{\theta}{2} & \cos\frac{\theta}{2} \end{bmatrix} \end{align}\end{split}\]

Parameters:

• qubits_idx (Iterable[int] | str) – Indices of the qubits on which the gates are applied. Defaults to ‘cycle’.

• depth (int) – Number of layers. Defaults to 1.

• param (Tensor | float | None) – Parameters of the gates. Defaults to None.

• param_sharing (bool) – Whether gates in the same layer share a parameter. Defaults to False.

cry(qubits_idx='cycle', depth=1, param=None, param_sharing=False)

Add controlled rotation gates about the y-axis.

For a 2-qubit quantum circuit, when qubits_idx is [0, 1], the matrix form of such a gate is:

\[\begin{split}\begin{align} \mathit{CR_Y} &=|0\rangle \langle 0|\otimes I + |1 \rangle \langle 1|\otimes R_Y\\ &= \begin{bmatrix} 1 & 0 & 0 & 0 \\ 0 & 1 & 0 & 0 \\ 0 & 0 & \cos\frac{\theta}{2} & -\sin\frac{\theta}{2} \\ 0 & 0 & \sin\frac{\theta}{2} & \cos\frac{\theta}{2} \end{bmatrix} \end{align}\end{split}\]

Parameters:

• qubits_idx (Iterable[int] | str) – Indices of the qubits on which the gates are applied. Defaults to ‘cycle’.

• depth (int) – Number of layers. Defaults to 1.

• param (Tensor | float | None) – Parameters of the gates. Defaults to None.

• param_sharing (bool) – Whether gates in the same layer share a parameter. Defaults to False.

crz(qubits_idx='cycle', depth=1, param=None, param_sharing=False)

Add controlled rotation gates about the z-axis.

For a 2-qubit quantum circuit, when qubits_idx is [0, 1], the matrix form of such a gate is:

\[\begin{split}\begin{align} \mathit{CR_Z} &= |0\rangle \langle 0|\otimes I + |1 \rangle \langle 1|\otimes R_Z\\ &= \begin{bmatrix} 1 & 0 & 0 & 0 \\ 0 & 1 & 0 & 0 \\ 0 & 0 & e^{-i\frac{\theta}{2}} & 0 \\ 0 & 0 & 0 & e^{i\frac{\theta}{2}} \end{bmatrix} \end{align}\end{split}\]

Parameters:

• qubits_idx (Iterable[int] | str) – Indices of the qubits on which the gates are applied. Defaults to ‘cycle’.

• depth (int) – Number of layers. Defaults to 1.

• param (Tensor | float | None) – Parameters of the gates. Defaults to None.

• param_sharing (bool) – Whether gates in the same layer share a parameter. Defaults to False.

cu(qubits_idx='cycle', depth=1, param=None, param_sharing=False)

Add controlled single-qubit rotation gates.

For a 2-qubit quantum circuit, when qubits_idx is [0, 1], the matrix form of such a gate is:

\[\begin{split}\begin{align} \mathit{CU} &= \begin{bmatrix} 1 & 0 & 0 & 0 \\ 0 & 1 & 0 & 0 \\ 0 & 0 & \cos\frac\theta2 &-e^{i\lambda}\sin\frac\theta2 \\ 0 & 0 & e^{i\phi}\sin\frac\theta2&e^{i(\phi+\lambda)}\cos\frac\theta2 \end{bmatrix} \end{align}\end{split}\]

Parameters:

• qubits_idx (Iterable[int] | str) – Indices of the qubits on which the gates are applied. Defaults to ‘cycle’.

• depth (int) – Number of layers. Defaults to 1.

• param (Tensor | float | None) – Parameters of the gates. Defaults to None.

• param_sharing (bool) – Whether gates in the same layer share a parameter. Defaults to False.

rxx(qubits_idx='linear', depth=1, param=None, param_sharing=False)

Add RXX gates.

The matrix form of such a gate is:

\[\begin{split}\begin{align} \mathit{R_{XX}}(\theta) = \begin{bmatrix} \cos\frac{\theta}{2} & 0 & 0 & -i\sin\frac{\theta}{2} \\ 0 & \cos\frac{\theta}{2} & -i\sin\frac{\theta}{2} & 0 \\ 0 & -i\sin\frac{\theta}{2} & \cos\frac{\theta}{2} & 0 \\ -i\sin\frac{\theta}{2} & 0 & 0 & \cos\frac{\theta}{2} \end{bmatrix} \end{align}\end{split}\]

Parameters:

• qubits_idx (Iterable[int] | str) – Indices of the qubits on which the gates are applied. Defaults to ‘linear’.

• depth (int) – Number of layers. Defaults to 1.

• param (Tensor | float | None) – Parameters of the gates. Defaults to None.

• param_sharing (bool) – Whether gates in the same layer share a parameter. Defaults to False.

ryy(qubits_idx='linear', depth=1, param=None, param_sharing=False)

Add RYY gates.

The matrix form of such a gate is:

\[\begin{split}\begin{align} \mathit{R_{YY}}(\theta) = \begin{bmatrix} \cos\frac{\theta}{2} & 0 & 0 & i\sin\frac{\theta}{2} \\ 0 & \cos\frac{\theta}{2} & -i\sin\frac{\theta}{2} & 0 \\ 0 & -i\sin\frac{\theta}{2} & \cos\frac{\theta}{2} & 0 \\ i\sin\frac{\theta}{2} & 0 & 0 & cos\frac{\theta}{2} \end{bmatrix} \end{align}\end{split}\]

Parameters:

• qubits_idx (Iterable[int] | str) – Indices of the qubits on which the gates are applied. Defaults to ‘linear’.

• depth (int) – Number of layers. Defaults to 1.

• param (Tensor | float | None) – Parameters of the gates. Defaults to None.

• param_sharing (bool) – Whether gates in the same layer share a parameter. Defaults to False.

rzz(qubits_idx='linear', depth=1, param=None, param_sharing=False)

Add RZZ gates.

The matrix form of such a gate is:

\[\begin{split}\begin{align} \mathit{R_{ZZ}}(\theta) = \begin{bmatrix} e^{-i\frac{\theta}{2}} & 0 & 0 & 0 \\ 0 & e^{i\frac{\theta}{2}} & 0 & 0 \\ 0 & 0 & e^{i\frac{\theta}{2}} & 0 \\ 0 & 0 & 0 & e^{-i\frac{\theta}{2}} \end{bmatrix} \end{align}\end{split}\]

Parameters:

• qubits_idx (Iterable[int] | str) – Indices of the qubits on which the gates are applied. Defaults to ‘linear’.

• depth (int) – Number of layers. Defaults to 1.

• param (Tensor | float | None) – Parameters of the gates. Defaults to None.

• param_sharing (bool) – Whether gates in the same layer share a parameter. Defaults to False.

ms(qubits_idx='cycle', depth=1)

Add Mølmer-Sørensen (MS) gates.

The matrix form of such a gate is:

\[\begin{split}\begin{align} \mathit{MS} = \mathit{R_{XX}}(-\frac{\pi}{2}) = \frac{1}{\sqrt{2}} \begin{bmatrix} 1 & 0 & 0 & i \\ 0 & 1 & i & 0 \\ 0 & i & 1 & 0 \\ i & 0 & 0 & 1 \end{bmatrix} \end{align}\end{split}\]

Parameters:

• qubits_idx (Iterable[int] | str) – Indices of the qubits on which the gates are applied. Defaults to ‘cycle’.

• depth (int) – Number of layers. Defaults to 1.

cswap(qubits_idx='cycle', depth=1)

Add CSWAP (Fredkin) gates.

The matrix form of such a gate is:

\[\begin{split}\begin{align} \mathit{CSWAP} = \begin{bmatrix} 1 & 0 & 0 & 0 & 0 & 0 & 0 & 0 \\ 0 & 1 & 0 & 0 & 0 & 0 & 0 & 0 \\ 0 & 0 & 1 & 0 & 0 & 0 & 0 & 0 \\ 0 & 0 & 0 & 1 & 0 & 0 & 0 & 0 \\ 0 & 0 & 0 & 0 & 1 & 0 & 0 & 0 \\ 0 & 0 & 0 & 0 & 0 & 0 & 1 & 0 \\ 0 & 0 & 0 & 0 & 0 & 1 & 0 & 0 \\ 0 & 0 & 0 & 0 & 0 & 0 & 0 & 1 \end{bmatrix} \end{align}\end{split}\]

Parameters:

• qubits_idx (Iterable[int] | str) – Indices of the qubits on which the gates are applied. Defaults to ‘cycle’.

• depth (int) – Number of layers. Defaults to 1.

ccx(qubits_idx='cycle', depth=1)

Add CCX (Toffoli) gates.

The matrix form of such a gate is:

\[\begin{split}\begin{align} \mathit{CCX} = \begin{bmatrix} 1 & 0 & 0 & 0 & 0 & 0 & 0 & 0 \\ 0 & 1 & 0 & 0 & 0 & 0 & 0 & 0 \\ 0 & 0 & 1 & 0 & 0 & 0 & 0 & 0 \\ 0 & 0 & 0 & 1 & 0 & 0 & 0 & 0 \\ 0 & 0 & 0 & 0 & 1 & 0 & 0 & 0 \\ 0 & 0 & 0 & 0 & 0 & 1 & 0 & 0 \\ 0 & 0 & 0 & 0 & 0 & 0 & 0 & 1 \\ 0 & 0 & 0 & 0 & 0 & 0 & 1 & 0 \end{bmatrix} \end{align}\end{split}\]

Parameters:

• qubits_idx (Iterable[int] | str) – Indices of the qubits on which the gates are applied. Defaults to ‘cycle’.

• depth (int) – Number of layers. Defaults to 1.

universal_two_qubits(qubits_idx='cycle', depth=1, param=None, param_sharing=False)

Add universal two-qubit gates. One of such a gate requires 15 parameters.

Parameters:

• qubits_idx (Iterable[int] | str) – Indices of the qubits on which the gates are applied. Defaults to ‘cycle’.

• depth (int) – Number of layers. Defaults to 1.

• param (Tensor | float | None) – Parameters of the gates. Defaults to None.

• param_sharing (bool) – Whether gates in the same layer share a parameter. Defaults to False.

universal_three_qubits(qubits_idx='cycle', depth=1, param=None, param_sharing=False)

Add universal three-qubit gates. One of such a gate requires 81 parameters.

Parameters:

• qubits_idx (Iterable[int] | str) – Indices of the qubits on which the gates are applied. Defaults to ‘cycle’.

• depth (int) – Number of layers. Defaults to 1.

• param (Tensor | float | None) – Parameters of the gates. Defaults to None.

• param_sharing (bool) – Whether gates in the same layer share a parameter. Defaults to False.

Raises:

ValueError – The param must be paddle.Tensor or float.

oracle(oracle, qubits_idx, depth=1, gate_name='O', latex_name=None, plot_width=None)

Add an oracle gate.

Parameters:

• oracle (<module 'paddle.tensor' from 'C:\\Users\\Cloud\\anaconda3\\envs\\pq\\lib\\site-packages\\paddle\\tensor\\__init__.py'>) – Unitary oracle to be implemented.

• qubits_idx (Iterable[Iterable[int]] | Iterable[int] | int) – Indices of the qubits on which the gates are applied.

• depth (int) – Number of layers. Defaults to 1.

• gate_name (str | None) – name of this oracle.

• latex_name (str | None) – latex name of this oracle, default to be the gate name.

• plot_width (float | None) – width of this gate in circuit plot, default to be proportional with the gate name.

control_oracle(oracle, qubits_idx, depth=1, gate_name='O', latex_name=None, plot_width=None)

Add a controlled oracle gate.

Parameters:

• oracle (Tensor) – Unitary oracle to be implemented.

• qubits_idx (Iterable[Iterable[int]] | Iterable[int]) – Indices of the qubits on which the gates are applied.

• depth (int) – Number of layers. Defaults to 1.

• gate_name (str | None) – name of this oracle.

• latex_name (str | None) – latex name of this oracle, default to be the gate name.

• plot_width (float | None) – width of this gate in circuit plot, default to be proportional with the gate name.

collapse(qubits_idx='full', desired_result=None, if_print=False, measure_basis='z')

Parameters:

• qubits_idx (Iterable[int] | int | str) – list of qubits to be collapsed. Defaults to 'full'.

• desired_result (int | str | None) – The desired result you want to collapse. Defaults to None meaning randomly choose one.

• if_print (bool) – whether print the information about the collapsed state. Defaults to False.

• measure_basis (Iterable[Tensor] | str) – The basis of the measurement. The quantum state will collapse to the corresponding eigenstate.

Raises:

• NotImplementedError – If the basis of measurement is not z. Other bases will be implemented in future.

• TypeError – cannot get probability of state when the backend is unitary_matrix.

Note

When desired_result is None, Collapse does not support gradient calculation

superposition_layer(qubits_idx=None, depth=1)

Add layers of Hadamard gates.

Parameters:

• qubits_idx (Iterable[int] | None) – Indices of the qubits on which the gates are applied. Defaults to None.

• depth (int) – Number of layers. Defaults to 1.

weak_superposition_layer(qubits_idx=None, depth=1)

Add layers of Ry gates with a rotation angle \(\pi/4\).

Parameters:

• qubits_idx (Iterable[int] | None) – Indices of the qubits on which the gates are applied. Defaults to None.

• depth (int) – Number of layers. Defaults to 1.

linear_entangled_layer(qubits_idx=None, depth=1)

Add linear entangled layers consisting of Ry gates, Rz gates, and CNOT gates.

Parameters:

• qubits_idx (Iterable[int] | None) – Indices of the qubits on which the gates are applied. Defaults to None.

• depth (int) – Number of layers. Defaults to 1.

real_entangled_layer(qubits_idx=None, depth=1)

Add strongly entangled layers consisting of Ry gates and CNOT gates.

Parameters:

• qubits_idx (Iterable[int] | None) – Indices of the qubits on which the gates are applied. Defaults to None.

• depth (int) – Number of layers. Defaults to 1.

complex_entangled_layer(qubits_idx=None, depth=1)

Add strongly entangled layers consisting of single-qubit rotation gates and CNOT gates.

Parameters:

• qubits_idx (Iterable[int] | None) – Indices of the qubits on which the gates are applied. Defaults to None.

• depth (int) – Number of layers. Defaults to 1.

real_block_layer(qubits_idx=None, depth=1)

Add weakly entangled layers consisting of Ry gates and CNOT gates.

Parameters:

• qubits_idx (Iterable[int] | None) – Indices of the qubits on which the gates are applied. Defaults to None.

• depth (int) – Number of layers. Defaults to 1.

complex_block_layer(qubits_idx=None, depth=1)

Add weakly entangled layers consisting of single-qubit rotation gates and CNOT gates.

Parameters:

• qubits_idx (Iterable[int] | None) – Indices of the qubits on which the gates are applied. Defaults to None.

• depth (int) – Number of layers. Defaults to 1.

bit_flip(prob, qubits_idx='full')

Add bit flip channels.

Parameters:

• prob (Tensor | float) – Probability of a bit flip.

• qubits_idx (Iterable[int] | int | str) – Indices of the qubits on which the channels are applied. Defaults to ‘full’.

phase_flip(prob, qubits_idx='full')

Add phase flip channels.

Parameters:

• prob (Tensor | float) – Probability of a phase flip.

• qubits_idx (Iterable[int] | int | str) – Indices of the qubits on which the channels are applied. Defaults to ‘full’.

bit_phase_flip(prob, qubits_idx='full')

Add bit phase flip channels.

Parameters:

• prob (Tensor | float) – Probability of a bit phase flip.

• qubits_idx (Iterable[int] | int | str) – Indices of the qubits on which the channels are applied. Defaults to ‘full’.

amplitude_damping(gamma, qubits_idx='full')

Add amplitude damping channels.

Parameters:

• gamma (Tensor | float) – Damping probability.

• qubits_idx (Iterable[int] | int | str) – Indices of the qubits on which the channels are applied. Defaults to ‘full’.

generalized_amplitude_damping(gamma, prob, qubits_idx='full')

Add generalized amplitude damping channels.

Parameters:

• gamma (Tensor | float) – Damping probability. Its value should be in the range \([0, 1]\).

• prob (Tensor | float) – Excitation probability. Its value should be in the range \([0, 1]\).

• qubits_idx (Iterable[int] | int | str) – Indices of the qubits on which the channels are applied. Defaults to ‘full’.

phase_damping(gamma, qubits_idx='full')

Add phase damping channels.

Parameters:

• gamma (Tensor | float) – Parameter of the phase damping channel.

• qubits_idx (Iterable[int] | int | str) – Indices of the qubits on which the channels are applied. Defaults to ‘full’.

depolarizing(prob, qubits_idx='full')

Add depolarizing channels.

Parameters:

• prob (Tensor | float) – Parameter of the depolarizing channel.

• qubits_idx (Iterable[int] | int | str) – Indices of the qubits on which the channels are applied. Defaults to ‘full’.

generalized_depolarizing(prob, qubits_idx)

Add a general depolarizing channel.

Parameters:

• prob (Tensor | float) – Probabilities corresponding to the Pauli basis.

• qubits_idx (Iterable[int] | int | str) – Indices of the qubits on which the channel is applied.

pauli_channel(prob, qubits_idx='full')

Add Pauli channels.

Parameters:

• prob (Tensor | float) – Probabilities corresponding to the Pauli X, Y, and Z operators.

• qubits_idx (Iterable[int] | int | str) – Indices of the qubits on which the channels are applied. Defaults to ‘full’.

reset_channel(prob, qubits_idx='full')

Add reset channels.

Parameters:

• prob (Tensor | float) – Probabilities of resetting to \(|0\rangle\) and to \(|1\rangle\).

• qubits_idx (Iterable[int] | int | str) – Indices of the qubits on which the channels are applied. Defaults to ‘full’.

thermal_relaxation(const_t, exec_time, qubits_idx='full')

Add thermal relaxation channels.

Parameters:

• const_t (Tensor | Iterable[float]) – \(T_1\) and \(T_2\) relaxation time in microseconds.

• exec_time (Tensor | float) – Quantum gate execution time in the process of relaxation in nanoseconds.

• qubits_idx (Iterable[int] | int | str) – Indices of the qubits on which the channels are applied. Defaults to ‘full’.

mixed_unitary_channel(num_unitary, qubits_idx='full')

Add mixed random unitary channels

Parameters:

• num_unitary (Tensor | int) – The amount of random unitaries to be generated.

• qubits_idx (Iterable[int] | int | str) – Indices of the qubits on which the channels act. Defaults to 'full'.

choi_channel(choi_repr, qubits_idx)

Add custom channels in the Choi representation.

Parameters:

• choi_repr (Iterable[Tensor]) – Choi representation of this channel.

• qubits_idx (Iterable[Iterable[int]] | Iterable[int] | int) – Indices of the qubits on which the channels are applied.

kraus_channel(kraus_oper, qubits_idx)

Add custom channels in the Kraus representation.

Parameters:

• kraus_oper (Iterable[Tensor]) – Kraus representation of this channel.

• qubits_idx (Iterable[Iterable[int]] | Iterable[int] | int) – Indices of the qubits on which the channels are applied.

stinespring_channel(stinespring_repr, qubits_idx)

Add custom channels in the Stinespring representation.

Parameters:

• stinespring_repr (Iterable[Tensor]) – Stinespring representation of this channel.

• qubits_idx (Iterable[Iterable[int]] | Iterable[int] | int) – Indices of the qubits on which the channels are applied.

unitary_matrix()

Get the unitary matrix form of the circuit.

Returns:

Unitary matrix form of the circuit.

Return type:

Tensor

property gate_history: List[Dict[str, str | List[int] | Tensor]]

List of gates information of circuit

Returns:

history of quantum gates of circuit

property depth: int

Depth of gate sequences.

Returns:

depth of this circuit

Note

The measurement is omitted, and all gates are assumed to have depth 1. See Niel’s answer in the [StackExchange](https://quantumcomputing.stackexchange.com/a/5772).

property qubit_history: List[List[Tuple[Dict[str, str | List[int] | Tensor], int]]]

gate information on each qubit

Returns:

list of gate history on each qubit

Note

The entry qubit_history[i][j][0/1] returns the gate information / gate index of the j-th gate applied on the i-th qubit.

plot(save_path=None, dpi=100, show=True, output=False, scale=1.0, tex=False)

display the circuit using matplotlib

Parameters:

• save_path (str | None) – the save path of image

• dpi (int | None) – dots per inches, here is resolution ratio

• show (bool | None) – whether execute plt.show()

• output (bool | None) – whether return the matplotlib.figure.Figure instance

• scale (float | None) – scale coefficient of figure, default to 1.0

• tex (bool | None) – a bool flag which controls latex fonts of gate display, default to False.

Returns:

a matplotlib.figure.Figure instance or None depends on output

Return type:

None | Figure

Note

Using plt.show() may cause a distortion, but it will not happen in the figure saved. If the depth is too long, there will be some patches unable to display. Setting tex = True requires that you have TeX and the other dependencies properly installed on your system. See https://matplotlib.org/stable/gallery/text_labels_and_annotations/tex_demo.html for more details.

extend(cir)

extend for quantum circuit

Parameters:

cir – a Circuit or a Sequential

Returns:

concatenation of two quantum circuits

forward(state=None)

forward the input

Parameters:

state (State | None) – initial state

Returns:

output quantum state

Return type:

State