Quantum Gates

API reference for all quantum gate functions in pyqpanda3. Every gate function returns a QGate object that can be composed into QCircuit and QProg structures.

QGate Class

QGate is the base type returned by all gate factory functions.

Signature

class QGate

Methods

Method	Signature	Description
qubits_num	qubits_num() -> int	Number of qubits the gate acts on
qubits	qubits() -> list[int]	All qubit indices the gate acts on
control_qubits	control_qubits() -> list[int]	Control qubit indices
target_qubits	target_qubits() -> list[int]	Target qubit indices
dagger	dagger() -> QGate	Return the dagger (conjugate transpose) of the gate
is_dagger	is_dagger() -> bool	Whether the gate is in dagger form
power	power(k: float) -> QGate	Raise the gate to a power
clear_control	clear_control() -> None	Remove all control qubits
control	control(qubit: int) -> QGate	Add a single control qubit, returning a controlled gate
control	control(qubits: list[int]) -> QGate	Add multiple control qubits, returning a controlled gate
matrix	matrix(expanded: bool = False) -> numpy.ndarray	Unitary matrix representation; if expanded is True, expand to full system size
gate_type	gate_type() -> GateType	Enum value identifying the gate type
remap	remap(qubit_map: dict[int, int]) -> QGate	Remap qubit indices using a mapping dict
remap	remap(qubit_list: list[int]) -> QGate	Remap qubit indices using an ordered list
parameters	parameters() -> list[float]	Gate parameters
set_parameters	set_parameters(params: list[float]) -> None	Set gate parameters
name	name() -> str	Gate name string

Single-Qubit Gates

H — Hadamard

H(qubit: int) -> QGate

Applies the Hadamard gate, creating equal superposition.

$$H=\frac{1}{\sqrt{2}}\left[\begin{array}{cc}1& 1\\ 1& -1\end{array}\right]$$

from pyqpanda3.core import H, CPUQVM, QProg, measure

qvm = CPUQVM()
prog = QProg()
prog << H(0)
prog << measure(0, 0)
qvm.run(prog, 1000)
result = qvm.result()
print(result.get_counts())

运行结果：

{'0': 515, '1': 485}

X — Pauli-X (NOT)

X(qubit: int) -> QGate

Bit-flip (NOT) gate.

$$X=\left[\begin{array}{cc}0& 1\\ 1& 0\end{array}\right]$$

Y — Pauli-Y

Y(qubit: int) -> QGate

$$Y=\left[\begin{array}{cc}0& -i\\ i& 0\end{array}\right]$$

Z — Pauli-Z

Z(qubit: int) -> QGate

Phase-flip gate.

$$Z=\left[\begin{array}{cc}1& 0\\ 0& -1\end{array}\right]$$

I — Identity

I(qubit: int) -> QGate

Identity gate (no operation).

$$I=\left[\begin{array}{cc}1& 0\\ 0& 1\end{array}\right]$$

S — Phase Gate

S(qubit: int) -> QGate

$$S=\left[\begin{array}{cc}1& 0\\ 0& i\end{array}\right]$$

T — T Gate (π/8 Gate)

T(qubit: int) -> QGate

$$T=\left[\begin{array}{cc}1& 0\\ 0& e^{i\pi /4}\end{array}\right]$$

X1 — SX Gate

X1(qubit: int) -> QGate

$$X1=\frac{1}{\sqrt{2}}\left[\begin{array}{cc}1& -i\\ -i& 1\end{array}\right]$$

Y1

Y1(qubit: int) -> QGate

$$Y1=\frac{1}{\sqrt{2}}\left[\begin{array}{cc}1& -1\\ 1& 1\end{array}\right]$$

Z1

Z1(qubit: int) -> QGate

$$Z1=\frac{1}{\sqrt{2}}\left[\begin{array}{cc}1-i& 0\\ 0& 1+i\end{array}\right]$$

P — Phase Gate (Parameterized)

P(qubit: int, theta: float) -> QGate

Parameter	Type	Description
qubit	int	Target qubit index
theta	float	Rotation angle in radians

$$P(\theta )=\left[\begin{array}{cc}1& 0\\ 0& e^{i\theta }\end{array}\right]$$

RX — Rotation around X

RX(qubit: int, theta: float) -> QGate

Parameter	Type	Description
qubit	int	Target qubit index
theta	float	Rotation angle in radians

$$R_X(\theta )=e^{-i\theta X/2}=\left[\begin{array}{cc}\cos (\theta /2)& -i\sin (\theta /2)\\ -i\sin (\theta /2)& \cos (\theta /2)\end{array}\right]$$

RY — Rotation around Y

RY(qubit: int, theta: float) -> QGate

$$R_Y(\theta )=e^{-i\theta Y/2}=\left[\begin{array}{cc}\cos (\theta /2)& -\sin (\theta /2)\\ \sin (\theta /2)& \cos (\theta /2)\end{array}\right]$$

RZ — Rotation around Z

RZ(qubit: int, theta: float) -> QGate

$$R_Z(\theta )=e^{-i\theta Z/2}=\left[\begin{array}{cc}{e}^{-i\theta /2}& 0\\ 0& e^{i\theta /2}\end{array}\right]$$

RPHI — R-Phi Gate

RPHI(control: int, theta: float, phi: float) -> QGate

Note: RPhi is a variational gate (VQGate) with a different signature. It is not the same as RPHI. See Variational Gate for details.

Parameter	Type	Description
control	int	Target qubit index
theta	float	Rotation angle
phi	float	Phase angle

$$R_{\text{PHI}}(\theta ,\varphi )=\left[\begin{array}{cc}\cos (\theta /2)& -i{e}^{-i\varphi }\sin (\theta /2)\\ -i{e}^{i\varphi }\sin (\theta /2)& \cos (\theta /2)\end{array}\right]$$

U1

U1(qubit: int, theta: float) -> QGate

Single-parameter gate. Equivalent to $P(\theta )$.

U2

U2(qubit: int, theta: float, phi: float) -> QGate

Parameter	Type	Description
qubit	int	Target qubit index
theta	float	First angle parameter
phi	float	Second angle parameter

$$U2(\theta ,\varphi )=\frac{1}{\sqrt{2}}\left[\begin{array}{cc}1& -e^{i\varphi }\\ e^{i\theta }& e^{i(\theta +\varphi )}\end{array}\right]$$

U3

U3(qubit: int, theta: float, phi: float, lambda: float) -> QGate

Parameter	Type	Description
qubit	int	Target qubit index
theta	float	Rotation angle
phi	float	First phase
lambda	float	Second phase

$$U3(\theta ,\varphi ,\lambda )=\left[\begin{array}{cc}\cos (\theta /2)& -e^{i\lambda }\sin (\theta /2)\\ e^{i\varphi }\sin (\theta /2)& e^{i(\varphi +\lambda )}\cos (\theta /2)\end{array}\right]$$

U4

U4(qubit: int, theta: float, phi: float, lambda: float, gamma: float) -> QGate

Parameter	Type	Description
qubit	int	Target qubit index
theta	float	First angle
phi	float	Second angle
lambda	float	Third angle
gamma	float	Fourth angle

$$U4(\theta ,\varphi ,\lambda ,\gamma )=\left[\begin{array}{cc}{e}^{i(\theta -\varphi /2-\gamma /2)}\cos (\lambda /2)& -e^{i(\theta -\varphi /2+\gamma /2)}\sin (\lambda /2)\\ e^{i(\theta +\varphi /2-\gamma /2)}\sin (\lambda /2)& e^{i(\theta +\varphi /2+\gamma /2)}\cos (\lambda /2)\end{array}\right]$$

IDLE

IDLE(qubit: int, nanoseconds: float) -> QGate

Parameter	Type	Description
qubit	int	Target qubit index
nanoseconds	float	Delay duration in nanoseconds

Two-Qubit Gates

CNOT — Controlled-NOT

CNOT(qubit1: int, qubit2: int) -> QGate

Parameter	Type	Description
qubit1	int	Control qubit index
qubit2	int	Target qubit index

$$\text{CNOT}=\left[\begin{array}{cccc}1& 0& 0& 0\\ 0& 1& 0& 0\\ 0& 0& 0& 1\\ 0& 0& 1& 0\end{array}\right]$$

from pyqpanda3.core import H, CNOT, CPUQVM, QProg, measure

qvm = CPUQVM()
prog = QProg()
# Create Bell state
prog << H(0) << CNOT(0, 1)
prog << measure(0, 0) << measure(1, 1)
qvm.run(prog, 1000)
print(qvm.result().get_counts())

运行结果：

{'00': 479, '11': 521}

CZ — Controlled-Z

CZ(qubit1: int, qubit2: int) -> QGate

$$\text{CZ}=\left[\begin{array}{cccc}1& 0& 0& 0\\ 0& 1& 0& 0\\ 0& 0& 1& 0\\ 0& 0& 0& -1\end{array}\right]$$

CP — Controlled-Phase

CP(control: int, target: int, theta: float) -> QGate

Parameter	Type	Description
control	int	Control qubit index
target	int	Target qubit index
theta	float	Phase angle in radians

$$\text{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]$$

CR — Controlled-Rotation (alias for CP)

CR(control: int, target: int, theta: float) -> QGate

Equivalent to CP.

CRX — Controlled-RX

CRX(control: int, target: int, theta: float) -> QGate

CRY — Controlled-RY

CRY(control: int, target: int, theta: float) -> QGate

CRZ — Controlled-RZ

CRZ(control: int, target: int, theta: float) -> QGate

SWAP

SWAP(qubit1: int, qubit2: int) -> QGate

$$\text{SWAP}=\left[\begin{array}{cccc}1& 0& 0& 0\\ 0& 0& 1& 0\\ 0& 1& 0& 0\\ 0& 0& 0& 1\end{array}\right]$$

ISWAP

ISWAP(qubit1: int, qubit2: int) -> QGate

$$\text{iSWAP}=\left[\begin{array}{cccc}1& 0& 0& 0\\ 0& 0& i& 0\\ 0& i& 0& 0\\ 0& 0& 0& 1\end{array}\right]$$

SQISWAP — Square-root iSWAP

SQISWAP(qubit1: int, qubit2: int) -> QGate

$$\text{SQISWAP}=\left[\begin{array}{cccc}1& 0& 0& 0\\ 0& \frac{1}{\sqrt{2}}& \frac{i}{\sqrt{2}}& 0\\ 0& \frac{i}{\sqrt{2}}& \frac{1}{\sqrt{2}}& 0\\ 0& 0& 0& 1\end{array}\right]$$

ECHO

ECHO(qubit: int, param: float = 0.0) -> QGate

Parameter	Type	Description
qubit	int	Target qubit index
param	float	Echo parameter (default 0.0)

CU — Controlled-U

CU(control: int, target: int, theta: float, phi: float, lambda: float, gamma: float) -> QGate

Parameter	Type	Description
control	int	Control qubit index
target	int	Target qubit index
theta	float	Rotation angle
phi	float	First phase
lambda	float	Second phase
gamma	float	Third phase

RXX — Rotation around XX

RXX(control: int, target: int, theta: float) -> QGate

$$R_{XX}(\theta )=e^{-i\theta X\otimes X/2}=\left[\begin{array}{cccc}\cos (\theta /2)& 0& 0& -i\sin (\theta /2)\\ 0& \cos (\theta /2)& -i\sin (\theta /2)& 0\\ 0& -i\sin (\theta /2)& \cos (\theta /2)& 0\\ -i\sin (\theta /2)& 0& 0& \cos (\theta /2)\end{array}\right]$$

RYY — Rotation around YY

RYY(control: int, target: int, theta: float) -> QGate

$$R_{YY}(\theta )=e^{-i\theta Y\otimes Y/2}=\left[\begin{array}{cccc}\cos (\theta /2)& 0& 0& i\sin (\theta /2)\\ 0& \cos (\theta /2)& -i\sin (\theta /2)& 0\\ 0& -i\sin (\theta /2)& \cos (\theta /2)& 0\\ i\sin (\theta /2)& 0& 0& \cos (\theta /2)\end{array}\right]$$

RZZ — Rotation around ZZ

RZZ(control: int, target: int, theta: float) -> QGate

$$R_{ZZ}(\theta )=e^{-i\theta Z\otimes Z/2}=\left[\begin{array}{cccc}{e}^{-i\theta /2}& 0& 0& 0\\ 0& e^{i\theta /2}& 0& 0\\ 0& 0& e^{i\theta /2}& 0\\ 0& 0& 0& e^{-i\theta /2}\end{array}\right]$$

RZX — Rotation around ZX

RZX(control: int, target: int, theta: float) -> QGate

$$R_{ZX}(\theta )=e^{-i\theta Z\otimes X/2}=\left[\begin{array}{cccc}\cos (\theta /2)& 0& -i\sin (\theta /2)& 0\\ 0& \cos (\theta /2)& 0& i\sin (\theta /2)\\ -i\sin (\theta /2)& 0& \cos (\theta /2)& 0\\ 0& i\sin (\theta /2)& 0& \cos (\theta /2)\end{array}\right]$$

Multi-Qubit Gates

TOFFOLI — CCX (Controlled-Controlled-NOT)

TOFFOLI(qubit1: int, qubit2: int, qubit3: int) -> QGate

Parameter	Type	Description
qubit1	int	First control qubit
qubit2	int	Second control qubit
qubit3	int	Target qubit

Flips the target qubit if and only if both control qubits are $|1⟩$.

Special Gates

BARRIER

BARRIER(qubits: list[int]) -> QGate

Parameter	Type	Description
qubits	list[int]	Qubit indices to apply barrier

Prevents optimization across the barrier during transpilation.

RESET

RESET(qubit: int) -> QGate

Parameter	Type	Description
qubit	int	Qubit index to reset to `

New in 0.5.0. Applies the native, non-unitary RESET channel: the qubit is measured and conditionally flipped, collapsing it to |0> with certainty while leaving the classical registers untouched. Supported on the CPU state-vector and density-matrix simulators; other backends raise at execution time, and controlled RESET has no physical definition. The operation round-trips through OriginIR and is parsed from OpenQASM 2.0 reset q[i]; statements; exporting it back to OpenQASM raises RuntimeError (use OriginIR instead).

from pyqpanda3.core import CPUQVM, QProg, RESET, X, measure

prog = QProg() << X(0) << RESET(0) << measure(0, 0)
qvm = CPUQVM()
qvm.run(prog, 100)
print(qvm.result().get_counts())

Output:

{'0': 100}

MS — Molmer-Sorensen Gate

MS(qubit1: int, qubit2: int) -> QGate

Two-qubit entangling gate used in trapped-ion quantum computing.

$$\text{MS}=\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]$$

Oracle

Oracle(qubits: list[int], matrix: numpy.ndarray, check_unitary: bool = True) -> QGate

Parameter	Type	Description
qubits	list[int]	Qubit indices the oracle acts on
matrix	numpy.ndarray	Complex unitary matrix
check_unitary	bool	Validate that matrix is unitary before constructing the gate (new in 0.5.0). Default True.

Creates a custom gate from a given unitary matrix.

The matrix is applied in the order the qubits are given: qubits[0] is the most significant factor of the matrix, matching the left-most term of the Kronecker product. On qubits [0, 1], X ⊗ I therefore flips qubit 0 while I ⊗ X flips qubit 1, and listing the qubits as [1, 0] swaps which qubit each factor acts on.

import numpy as np
from pyqpanda3.core import Oracle, CPUQVM, QProg

x = np.array([[0, 1], [1, 0]], dtype=complex)
i = np.eye(2, dtype=complex)

# qubits[0] is the left-most factor, so X acts on qubit 0
qvm = CPUQVM()
qvm.run(QProg() << Oracle([0, 1], np.kron(x, i)), 1)
print({format(k, '02b'): round(abs(v), 3)
       for k, v in enumerate(qvm.result().get_state_vector()) if abs(v) > 1e-9})

Output:

{'10': 1.0}

check_unitary rejects a matrix that is not unitary, which would define a non-physical gate. Leave it enabled unless the matrix comes from a trusted source and the validation is a measurable cost:

import numpy as np
from pyqpanda3.core import Oracle

not_unitary = np.array([[1, 1], [0, 1]], dtype=complex)

try:
    Oracle([0], not_unitary)
except ValueError as e:
    print(type(e).__name__, "-", e)

gate = Oracle([0], not_unitary, check_unitary=False)
print("built without validation:", type(gate).__name__)

Output:

ValueError - Non-unitary matrix for QOracle-gate.
built without validation: QGate

Gate Operations

All QGate objects support the following operations:

Dagger

from pyqpanda3.core import H

gate = H(0)
dg = gate.dagger()  # Hermitian conjugate

Control

from pyqpanda3.core import X

gate = X(1)
cgate = gate.control([0])  # CNOT with qubit 0 as control

Power

from pyqpanda3.core import S

gate = S(0)
t_gate = gate.power(2)  # S^2 = Z

See Also

• Circuit — QCircuit and QProg for composing gates
• Enums — GateType enumeration
• Variational Gate — Parameterized gate variants

---

create_gate

Creates a quantum gate by specifying its name, target qubits, and parameters. This is a generic factory function that constructs any supported gate type dynamically.

Signature

create_gate(gate_name: str, qubits: list[int], params: list[float]) -> QGate

Parameters

Parameter	Type	Description
gate_name	str	Name of the gate to create (e.g., "H", "RX", "CNOT")
qubits	list[int]	List of target qubit indices
params	list[float]	List of parameter values (empty for non-parameterized gates)

Examples

from pyqpanda3.core import create_gate

# Create a Hadamard gate on qubit 0
h = create_gate("H", [0], [])

# Create an RX rotation gate on qubit 1 with angle 1.57
rx = create_gate("RX", [1], [1.57])

# Create a CNOT gate with control=0, target=1
cnot = create_gate("CNOT", [0, 1], [])