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{array}{r}H=\frac{1}{\sqrt{2}}\left[\begin{array}{cc}1& 1\\ 1& -1\end{array}\right]\end{array}$$

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{array}{r}S=\left[\begin{array}{cc}1& 0\\ 0& i\end{array}\right]\end{array}$$

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{array}{r}{S}^{†}=\left[\begin{array}{cc}1& 0\\ 0& -i\end{array}\right]\end{array}$$

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{array}{r}T=\left[\begin{array}{cc}1& 0\\ 0& e^{\frac{i\pi }{4}}\end{array}\right]\end{array}$$

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{array}{r}{T}^{†}=\left[\begin{array}{cc}1& 0\\ 0& e^{-\frac{i\pi }{4}}\end{array}\right]\end{array}$$

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{array}{r}X=\left[\begin{array}{cc}0& 1\\ 1& 0\end{array}\right]\end{array}$$

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{array}{r}Y=\left[\begin{array}{cc}0& -i\\ i& 0\end{array}\right]\end{array}$$

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{array}{r}Z=\left[\begin{array}{cc}1& 0\\ 0& -1\end{array}\right]\end{array}$$

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{array}{r}P(\theta )=\left[\begin{array}{cc}1& 0\\ 0& e^{i\theta }\end{array}\right]\end{array}$$

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{array}{r}{R}_X(\theta )=\left[\begin{array}{cc}\cos \frac{\theta }{2}& -i\sin \frac{\theta }{2}\\ -i\sin \frac{\theta }{2}& \cos \frac{\theta }{2}\end{array}\right]\end{array}$$

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{array}{r}{R}_Y(\theta )=\left[\begin{array}{cc}\cos \frac{\theta }{2}& -\sin \frac{\theta }{2}\\ \sin \frac{\theta }{2}& \cos \frac{\theta }{2}\end{array}\right]\end{array}$$

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{array}{r}{R}_Z(\theta )=\left[\begin{array}{cc}{e}^{-i\frac{\theta }{2}}& 0\\ 0& e^{i\frac{\theta }{2}}\end{array}\right]\end{array}$$

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{array}{r}\begin{array}{c}{U}_3(\theta ,\varphi ,\lambda )=\left[\begin{array}{cc}\cos \frac{\theta }{2}& -e^{i\lambda }\sin \frac{\theta }{2}\\ e^{i\varphi }\sin \frac{\theta }{2}& e^{i(\varphi +\lambda )}\cos \frac{\theta }{2}\end{array}\right]\end{array}\end{array}$$

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{array}{r}\begin{array}{rl}\mathit{CNOT}& =|0⟩⟨0|\otimes I+|1⟩⟨1|\otimes X\\ & =\left[\begin{array}{cccc}1& 0& 0& 0\\ 0& 1& 0& 0\\ 0& 0& 0& 1\\ 0& 0& 1& 0\end{array}\right]\end{array}\end{array}$$

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{array}{r}\begin{array}{rl}\mathit{CY}& =|0⟩⟨0|\otimes I+|1⟩⟨1|\otimes Y\\ & =\left[\begin{array}{cccc}1& 0& 0& 0\\ 0& 1& 0& 0\\ 0& 0& 0& -1j\\ 0& 0& 1j& 0\end{array}\right]\end{array}\end{array}$$

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{array}{r}\begin{array}{rl}\mathit{CZ}& =|0⟩⟨0|\otimes I+|1⟩⟨1|\otimes Z\\ & =\left[\begin{array}{cccc}1& 0& 0& 0\\ 0& 1& 0& 0\\ 0& 0& 1& 0\\ 0& 0& 0& -1\end{array}\right]\end{array}\end{array}$$

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{array}{r}\begin{array}{c}\mathit{SWAP}=\left[\begin{array}{cccc}1& 0& 0& 0\\ 0& 0& 1& 0\\ 0& 1& 0& 0\\ 0& 0& 0& 1\end{array}\right]\end{array}\end{array}$$

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{array}{r}\begin{array}{c}\mathit{CP}(\theta )=\left[\begin{array}{cccc}1& 0& 0& 0\\ 0& 1& 0& 0\\ 0& 0& 1& 0\\ 0& 0& 0& e^{i\theta }\end{array}\right]\end{array}\end{array}$$

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{array}{r}\begin{array}{rl}{\mathit{CR}}_{\mathit{X}}& =|0⟩⟨0|\otimes I+|1⟩⟨1|\otimes R_X\\ & =\left[\begin{array}{cccc}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{array}\right]\end{array}\end{array}$$

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{array}{r}\begin{array}{rl}{\mathit{CR}}_{\mathit{Y}}& =|0⟩⟨0|\otimes I+|1⟩⟨1|\otimes R_Y\\ & =\left[\begin{array}{cccc}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{array}\right]\end{array}\end{array}$$

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{array}{r}\begin{array}{rl}{\mathit{CR}}_{\mathit{Z}}& =|0⟩⟨0|\otimes I+|1⟩⟨1|\otimes R_Z\\ & =\left[\begin{array}{cccc}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{array}\right]\end{array}\end{array}$$

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{array}{r}\begin{array}{rl}\mathit{CU}& =\left[\begin{array}{cccc}1& 0& 0& 0\\ 0& 1& 0& 0\\ 0& 0& \cos \frac{\theta }{2}& -e^{i\lambda }\sin \frac{\theta }{2}\\ 0& 0& e^{i\varphi }\sin \frac{\theta }{2}& e^{i(\varphi +\lambda )}\cos \frac{\theta }{2}\end{array}\right]\end{array}\end{array}$$

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{array}{r}\begin{array}{c}{\mathit{R}}_{\mathit{XX}}(\theta )=\left[\begin{array}{cccc}\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{array}\right]\end{array}\end{array}$$

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{array}{r}\begin{array}{c}{\mathit{R}}_{\mathit{YY}}(\theta )=\left[\begin{array}{cccc}\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{array}\right]\end{array}\end{array}$$

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{array}{r}\begin{array}{c}{\mathit{R}}_{\mathit{ZZ}}(\theta )=\left[\begin{array}{cccc}{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{array}\right]\end{array}\end{array}$$

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{array}{r}\begin{array}{c}\mathit{MS}={\mathit{R}}_{\mathit{XX}}(-\frac{\pi }{2})=\frac{1}{\sqrt{2}}\left[\begin{array}{cccc}1& 0& 0& i\\ 0& 1& i& 0\\ 0& i& 1& 0\\ i& 0& 0& 1\end{array}\right]\end{array}\end{array}$$

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{array}{r}\begin{array}{c}\mathit{CSWAP}=\left[\begin{array}{cccccccc}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{array}\right]\end{array}\end{array}$$

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{array}{r}\begin{array}{c}\mathit{CCX}=\left[\begin{array}{cccccccc}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{array}\right]\end{array}\end{array}$$

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⟩$ and to $|1⟩$.

• 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