线路 -- Qubit, CBit, Operation, QGate, QCircuit, QProg

pyqpanda3 中量子线路构建的 API 参考。这些类构成了描述量子计算的核心构建模块：量子比特引用、操作、门、线路和程序。

---

Qubit

表示由数字地址标识的量子比特（qubit）。Qubit 对象是构建门和线路时使用的轻量级句柄。

签名

Qubit(qubit: int)

参数

参数	类型	说明
qubit	int	量子比特的整数地址（索引）。

方法

方法	返回类型	说明
get_qubit_addr()	int	返回此量子比特的地址（索引）。

特殊方法

• __int__() -- 将量子比特转换为其整数地址。
• __repr__() -- 返回字符串表示，例如 Qubit(0)。

示例

from pyqpanda3.core import Qubit

q0 = Qubit(0)
q1 = Qubit(1)

print(q0)               # Qubit(0)
print(int(q0))          # 0
print(q0.get_qubit_addr())  # 0

另见

• CBit -- 经典比特类。
• QCircuit -- 线路操作量子比特索引。

---

CBit

表示用于存储测量结果的经典比特。与 Qubit 类似，它是由数字地址标识的轻量级句柄。

签名

CBit(addr: int)

参数为位置参数（positional-only）。

参数

参数	类型	说明
addr	int	经典比特的整数地址（索引）。

方法

方法	返回类型	说明
get_cbit_addr()	int	返回此经典比特的地址（索引）。

特殊方法

• __int__() -- 将经典比特转换为其整数地址。
• __repr__() -- 返回字符串表示，例如 CBit(0)。

示例

from pyqpanda3.core import CBit

c0 = CBit(0)
c1 = CBit(1)

print(c0)               # CBit(0)
print(int(c0))          # 0
print(c0.get_cbit_addr())  # 0

另见

• Qubit -- 量子比特类。
• measure -- 测量操作将量子比特映射到经典比特。

---

Operation

量子程序中所有操作的基类。QGate 继承自 Operation。Operation 携带关于其类型、目标量子比特、控制量子比特和关联的经典比特（用于测量操作）的元数据。

签名

Operation()

属性

属性	类型	说明
m_operation_type	OpType	此操作的类型（Gate、Measure 等）。
m_target_qubits	list[int]	目标量子比特索引。
m_control_qubits	list[int]	控制量子比特索引。
m_measure_cbits	list[int]	与测量关联的经典比特索引。

方法

方法	返回类型	说明
is_controlled()	bool	如果此操作至少有一个控制量子比特则返回 True。

示例

from pyqpanda3.core import H, CNOT

# H is a single-qubit gate (Operation subclass)
h_gate = H(0)
print(h_gate.m_operation_type)    # OpType.Gate
print(h_gate.m_target_qubits)     # [0]
print(h_gate.is_controlled())      # False
# CNOT is a two-qubit controlled gate
cnot = CNOT(0, 1)
print(cnot.m_control_qubits)      # [0]
print(cnot.m_target_qubits)       # [1]
print(cnot.is_controlled())        # True

另见

• QGate -- 量子门类，继承自 Operation。
• OpType -- 操作类型枚举。

---

QGate

表示量子门操作。QGate 继承自 Operation，并添加了门特有的功能，如矩阵表示、门类型、参数、dagger 和幂运算以及控制量子比特管理。

签名

QGate 实例通过模块级门工厂函数（如 H、X、CNOT、RX 等）创建，而非直接调用 QGate 构造函数。

# 通过工厂函数的典型构造方式
gate = H(0)                    # 单量子比特门
gate = CNOT(0, 1)              # 双量子比特门
gate = RX(0, 3.14)             # 参数化门

方法

qubits_num

qubits_num() -> int

返回此门作用的总量子比特数（包括目标和控制量子比特）。

qubits

qubits() -> list[int]

返回目标量子比特索引。

control_qubits

control_qubits() -> list[int]

返回此门的控制量子比特索引。

target_qubits

target_qubits() -> list[int]

返回目标量子比特索引。

dagger

dagger() -> QGate

返回一个新的 QGate，是该门的厄米共轭（adjoint）。原始门不会被修改。

is_dagger

is_dagger() -> bool

如果此门处于 dagger（伴随）形式则返回 True。

power

power(k: int) -> QGate

返回一个新门，表示此门的整数次幂 k。

参数	类型	说明
k	int	指数。

clear_control

clear_control() -> None

移除此门的所有控制量子比特。

control

control(qubit: int) -> QGate
control(qubits: list[int]) -> QGate

向此门添加一个或多个控制量子比特。返回一个新的 QGate，原始门不会被修改。

参数	类型	说明
qubit	int	要添加的单个控制量子比特索引。
qubits	list[int]	要添加的控制量子比特索引列表。

matrix

matrix(expanded: bool = False) -> numpy.ndarray

返回此门的矩阵表示。当 expanded 为 True 时，矩阵扩展到包含控制量子比特的完整量子比特空间。

参数	类型	说明
expanded	bool	是否返回扩展矩阵（默认 False）。

gate_type

gate_type() -> GateType

返回此门的 GateType 枚举值。

remap

remap(mapping: dict[int, int]) -> QGate
remap(mapping: list[int]) -> QGate

返回一个新门，其量子比特索引根据提供的映射重新映射。

参数	类型	说明
mapping	dict[int, int] 或 list[int]	将旧量子比特索引映射到新索引的字典，或位置 i 给出量子比特 i 的新索引的列表。

parameters

parameters() -> list[float]

返回此门的参数列表（非参数化门为空列表）。

set_parameters

set_parameters(params: list[float]) -> None

设置此门的参数。

参数	类型	说明
params	list[float]	新的参数值。

name

name() -> str

返回此门的名称。

示例

from pyqpanda3.core import H, X, RX, CNOT

# 基本门属性
h = H(0)
print(h.gate_type())    # GateType.H
print(h.qubits())       # [0]
print(h.qubits_num())   # 1
print(h.name())         # "H"

# 参数化门
rx = RX(0, 1.57)
print(rx.parameters())  # [1.57]
rx.set_parameters([3.14])
print(rx.parameters())  # [3.14]

# Dagger（伴随）
h_dag = h.dagger()
print(h_dag.is_dagger())  # True

# 幂
rx_squared = rx.power(2)

# 控制量子比特
cnot = CNOT(0, 1)
print(cnot.control_qubits())  # [0]
print(cnot.target_qubits())   # [1]

# 向单量子比特门添加控制
controlled_h = H(0).control(2)
print(controlled_h.control_qubits())  # [2]

# 添加多个控制
controlled_x = X(0).control([2, 3])
print(controlled_x.control_qubits())  # [2, 3]

# 清除控制
controlled_x.clear_control()
print(controlled_x.control_qubits())  # []

# 矩阵表示
import numpy as np
mat = H(0).matrix()
print(mat.shape)  # (2, 2)

另见

• 量子门 -- 门工厂函数完整列表。
• GateType -- 门类型枚举。
• Operation -- 基类。

---

QCircuit

表示量子线路：一个有序的量子门操作序列。线路可以使用 << 运算符组合，支持 dagger、控制、深度分析和矩阵计算等操作。

签名

QCircuit()                    # 空线路
QCircuit(qubits_num: int)     # 具有指定寄存器大小的线路
QCircuit(circuit: QCircuit)   # 拷贝构造函数

参数

参数	类型	说明
qubits_num	int	要在线路寄存器中分配的量子比特数。
circuit	QCircuit	要拷贝的现有线路。

方法

size

size() -> int

返回线路中的操作数量。

append

append(gate: QGate) -> None
append(circuit: QCircuit) -> None

向此线路追加一个门或另一个线路。

参数	类型	说明
gate	QGate	要追加的量子门。
circuit	QCircuit	要追加的线路。

clear

clear() -> None

移除此线路中的所有操作。

matrix

matrix() -> numpy.ndarray

返回整个线路的幺正矩阵表示。

qubits

qubits() -> list[int]

返回此线路中使用的量子比特索引列表。

target_qubits

target_qubits() -> list[int]

返回此线路中使用的目标量子比特索引。

control_qubits

control_qubits() -> list[int]

返回此线路中使用的控制量子比特索引。

dagger

dagger() -> QCircuit

返回一个新的 QCircuit，其中每个门被替换为其厄米共轭。原始线路不会被修改。

control

control(qubit: int) -> QCircuit
control(qubits: list[int]) -> QCircuit

向整个线路添加一个或多个控制量子比特。返回一个新的 QCircuit，原始线路不会被修改。

参数	类型	说明
qubit	int	要添加的单个控制量子比特索引。
qubits	list[int]	要添加的控制量子比特索引列表。

clear_control

clear_control() -> None

移除此线路的所有控制量子比特。

set_name

set_name(name: str) -> None

为线路设置自定义名称。

参数	类型	说明
name	str	要分配的名称。

name

name() -> str

返回线路的名称。

operations

operations() -> list

返回线路中的所有操作列表（可能包含 QGate 和嵌套的 QCircuit 对象）。

gate_operations

gate_operations(only_q2: bool = False) -> list[QGate]

返回所有门级操作，展平嵌套线路。当 only_q2 为 True 时，仅返回双量子比特门。

参数	类型	说明
only_q2	bool	如果为 True，仅返回双量子比特门（默认 False）。

num_2q_gate

num_2q_gate() -> int

返回线路中双量子比特门的数量。

depth

depth(only_q2: bool = False) -> int

返回线路深度（顺序门层数）。当 only_q2 为 True 时，仅考虑双量子比特门。

参数	类型	说明
only_q2	bool	如果为 True，仅使用双量子比特门计算深度（默认 False）。

count_ops

count_ops(only_q2: bool = False) -> dict[str, int]

返回将门名称映射到其出现次数的字典。

参数	类型	说明
only_q2	bool	如果为 True，仅统计双量子比特门（默认 False）。

get_register_size

get_register_size() -> int

返回为此线路分配的量子比特寄存器大小。

expand

expand() -> QCircuit

返回一个新线路，其中所有嵌套子线路被展平为门序列。

originir

originir(precision: int = 8) -> str

返回线路的 OriginIR 字符串表示。

参数	类型	说明
precision	int	参数值的浮点精度（默认 8）。

remap

remap(mapping: list[int]) -> QCircuit
remap(mapping: dict[int, int]) -> QCircuit

返回一个新线路，其量子比特索引根据提供的映射重新映射。

参数	类型	说明
mapping	list[int] 或 dict[int, int]	将旧量子比特索引映射到新索引的列表或字典。

运算符

<<（左移）

追加一个门或线路。返回线路本身，支持链式调用。

circuit << gate         # 追加一个 QGate
circuit << other_circ   # 追加一个 QCircuit

特殊方法

• __str__() -- 返回基于文本的线路图。
• __lshift__() -- 实现 << 运算符用于追加门和线路。

示例

基本线路构建

from pyqpanda3.core import QCircuit, H, X, CNOT, T

# 创建空线路
circ = QCircuit()

# 使用 << 追加门
circ << H(0) << CNOT(0, 1)

print(circ.size())   # 2
print(circ.qubits()) # [0, 1]

带寄存器大小的线路

from pyqpanda3.core import QCircuit, H, CNOT

circ = QCircuit(3)
circ << H(0) << CNOT(0, 1) << X(2)

print(circ.get_register_size())  # 3
print(circ.size())               # 3

组合线路

from pyqpanda3.core import QCircuit, H, CNOT, T, S

# 子线路 A
sub_a = QCircuit()
sub_a << H(0) << CNOT(0, 1)

# 子线路 B
sub_b = QCircuit()
sub_b << T(0) << S(1)

# 使用 << 组合
full = QCircuit()
full << sub_a << sub_b

print(full.size())  # 4

分析：深度和门计数

from pyqpanda3.core import QCircuit, H, CNOT, T

circ = QCircuit()
circ << H(0) << H(1) << CNOT(0, 1) << T(0) << T(1)

print(circ.depth())          # 3 (H 层, CNOT 层, T 层)
print(circ.depth(only_q2=True))  # 1 (仅 CNOT 层)
print(circ.num_2q_gate())    # 1
print(circ.count_ops())      # {'H': 2, 'CNOT': 1, 'T': 2}

Dagger 和控制

from pyqpanda3.core import QCircuit, H, CNOT, RX

circ = QCircuit()
circ << H(0) << CNOT(0, 1) << RX(1, 1.57)

# 整个线路的 dagger
circ_dag = circ.dagger()

# 向整个线路添加控制量子比特
ctrl_circ = QCircuit()
ctrl_circ << H(0) << CNOT(0, 1)
ctrl_circ.control([2])

print(ctrl_circ.control_qubits())  # [2]

矩阵表示

import numpy as np
from pyqpanda3.core import QCircuit, H, X

circ = QCircuit()
circ << H(0) << X(1)

mat = circ.matrix()
print(mat.shape)  # (4, 4)

OriginIR 输出

from pyqpanda3.core import QCircuit, H, CNOT, RX

circ = QCircuit()
circ << H(0) << CNOT(0, 1) << RX(1, 1.57)

print(circ.originir())

重映射量子比特

from pyqpanda3.core import QCircuit, H, CNOT

circ = QCircuit()
circ << H(0) << CNOT(0, 1)

# 重映射：量子比特 0 -> 2，量子比特 1 -> 3
remapped = circ.remap([2, 3])
print(remapped.qubits())  # [2, 3]

另见

• QProg -- 量子程序（线路加测量和控制流）。
• QGate -- 量子门类。
• 量子门 -- 门工厂函数完整列表。
• OriginIR -- OriginIR 中间表示。

---

QProg

表示量子程序：一个完整的量子计算，可以包括门、线路、测量和动态控制流（经典条件分支和循环）。QProg 是提交程序到模拟器或量子硬件时使用的顶级容器。

签名

QProg()                                       # 空程序
QProg(qubits_num: int)                        # 具有指定量子比特数的程序
QProg(prog: QProg)                            # 拷贝构造函数
QProg(originir_src: str, is_file: bool = False)  # 从 OriginIR 源码或文件
QProg(node: QCircuit)                         # 从 QCircuit

参数

参数	类型	说明
qubits_num	int	要分配的量子比特数。
prog	QProg	要拷贝的现有程序。
originir_src	str	OriginIR 源码字符串或文件路径。
is_file	bool	如果为 True，originir_src 被视为文件路径（默认 False）。
node	QCircuit	用于初始化程序的线路。

方法

qubits_num

qubits_num() -> int

返回程序中使用的量子比特数。

cbits_num

cbits_num() -> int

返回程序中使用的经典比特数。

qubits

qubits() -> list[int]

返回程序中使用的量子比特索引。

cbits

cbits() -> list[int]

返回程序中使用的经典比特索引。

operations

operations() -> list

返回程序中的所有操作（门、测量、子程序等）。

gate_operations

gate_operations(only_q2: bool = False) -> list[QGate]

返回所有门级操作，展平嵌套结构。当 only_q2 为 True 时，仅返回双量子比特门。

参数	类型	说明
only_q2	bool	如果为 True，仅返回双量子比特门（默认 False）。

name

name() -> str

返回程序的名称。

get_measure_nodes

get_measure_nodes() -> list

返回程序中的所有测量节点。

flatten

flatten() -> QProg

返回一个新程序，其中所有嵌套子程序被展平为扁平序列。

to_circuit

to_circuit() -> QCircuit

将程序转换为 QCircuit（不包括测量操作）。

count_ops

count_ops(only_q2: bool = False) -> dict[str, int]

返回将操作名称映射到其计数的字典。

参数	类型	说明
only_q2	bool	如果为 True，仅统计双量子比特门（默认 False）。

depth

depth(only_q2: bool = False) -> int

返回程序深度（顺序门层数）。

参数	类型	说明
only_q2	bool	如果为 True，仅使用双量子比特门计算深度（默认 False）。

clear

clear() -> None

移除程序中的所有操作。

append

append(gate: QGate) -> None
append(circuit: QCircuit) -> None
append(prog: QProg) -> None
append(measure: MeasureNode) -> None

向程序追加一个操作。接受门、线路、程序和测量节点。

参数	类型	说明
gate	QGate	要追加的量子门。
circuit	QCircuit	要追加的线路。
prog	QProg	要追加的程序。
measure	MeasureNode	要追加的测量节点。

remap

remap(remap_qubits: list[int], remap_cbits: list[int]) -> QProg
remap(remap_qubits: dict[int, int], remap_cbits: dict[int, int] = {}) -> QProg

返回一个新程序，其量子比特和经典比特索引被重新映射。

参数	类型	说明
remap_qubits	list[int] 或 dict[int, int]	量子比特索引映射。
remap_cbits	list[int] 或 dict[int, int]	经典比特索引映射。

originir

originir(precision: int = 8) -> str

返回程序的 OriginIR 字符串表示。

参数	类型	说明
precision	int	参数值的浮点精度（默认 8）。

originbis

originbis() -> bytes

获取程序的 OriginBIS 二进制序列化。

from_originbis

from_originbis(data: bytes) -> None

从 OriginBIS 二进制数据反序列化程序。

参数	类型	说明
data	bytes	OriginBIS 二进制数据。

to_instruction

to_instruction(backend: str, offset: int = 1, is_scheduling: bool = False) -> str

将程序转换为与指定后端兼容的 JSON 指令字符串。

参数	类型	说明
backend	str	芯片后端名称，用于指令格式化。
offset	int	量子比特索引偏移（默认 1）。
is_scheduling	bool	是否包含调度信息（默认 False）。

运算符

<<（左移）

追加一个门、线路、程序或测量节点。返回程序本身，支持链式调用。

prog << gate          # 追加一个 QGate
prog << circuit       # 追加一个 QCircuit
prog << other_prog    # 追加一个 QProg
prog << measure_node  # 追加一个 MeasureNode

特殊方法

• __str__() -- 返回程序的基于文本的线路图。

示例

带测量的基本程序

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

prog = QProg()
prog << H(0) << CNOT(0, 1) << measure(0, 0) << measure(1, 1)

print(prog.qubits_num())  # 2
print(prog.cbits_num())   # 2
print(prog.qubits())      # [0, 1]
print(prog.cbits())       # [0, 1]

从 OriginIR 创建程序

from pyqpanda3.core import QProg

# 从 OriginIR 字符串
ir_source = """
QINIT 2
CREG 2
H q[0]
CNOT q[0],q[1]
MEASURE q[0],c[0]
MEASURE q[1],c[1]
"""
prog = QProg(ir_source)
print(prog.originir())

从 QCircuit 创建程序

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

circ = QCircuit()
circ << H(0) << CNOT(0, 1)

prog = QProg(circ)
prog << measure(0, 0) << measure(1, 1)

分析：深度和门计数

from pyqpanda3.core import QProg, H, CNOT, RX, T

prog = QProg()
prog << H(0) << H(1) << CNOT(0, 1) << RX(1, 0.5) << T(0)

print(prog.depth())          # 3
print(prog.depth(only_q2=True))  # 1
print(prog.count_ops())      # {'H': 2, 'CNOT': 1, 'RX': 1, 'T': 1}

展平并转换为线路

from pyqpanda3.core import QProg, QCircuit, H, CNOT

# 嵌套结构
sub = QCircuit()
sub << H(0) << CNOT(0, 1)

prog = QProg()
prog << sub << H(2)

# 展平为线性门序列
flat_prog = prog.flatten()

# 转换为线路（不包括测量）
circ = prog.to_circuit()
print(circ.qubits())  # [0, 1, 2]

重映射量子比特和经典比特

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

prog = QProg()
prog << H(0) << CNOT(0, 1) << measure(0, 0) << measure(1, 1)

# 使用列表重映射：量子比特 0->3，1->4；经典比特 0->5，1->6
remapped = prog.remap([3, 4], [5, 6])
print(remapped.qubits())  # [3, 4]
print(remapped.cbits())   # [5, 6]

# 使用字典重映射
remapped2 = prog.remap({0: 3, 1: 4}, {0: 5, 1: 6})

导出为后端指令

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

prog = QProg()
prog << H(0) << CNOT(0, 1) << measure(0, 0) << measure(1, 1)

json_instr = prog.to_instruction("origin_72", offset=1, is_scheduling=False)
print(json_instr)

获取测量节点

from pyqpanda3.core import QProg, H, measure

prog = QProg()
prog << H(0) << measure(0, 0)

measure_nodes = prog.get_measure_nodes()
print(len(measure_nodes))  # 1

另见

• QCircuit -- 量子线路（仅包含门的容器）。
• QGate -- 量子门类。
• MeasureNode -- 测量节点类。
• 动态线路 -- QProg 的条件和循环构造。
• OriginIR -- OriginIR 中间表示。
• 模拟器 -- 在模拟器上运行程序。

---

draw_qprog

将量子程序或线路绘制为文本图或 LaTeX 源码。此函数同时接受 QProg 和 QCircuit 对象。

签名

draw_qprog(qprog: QProg, p: PIC_TYPE = PIC_TYPE.TEXT, expend_map: dict[str, int] = {'all': 1}, param_show: bool = False, with_logo: bool = False, line_length: int = 100, output_file: str = '', encode: str = 'utf-8') -> str
draw_qprog(circuit: QCircuit, p: PIC_TYPE = PIC_TYPE.TEXT, ...) -> str

参数

参数	类型	默认值	说明
qprog	QProg	—	要绘制的量子程序
circuit	QCircuit	—	要绘制的量子线路
p	PIC_TYPE	PIC_TYPE.TEXT	输出格式：PIC_TYPE.TEXT 为 ASCII 文本，PIC_TYPE.LATEX 为 LaTeX
expend_map	dict[str, int]	{'all': 1}	要展开的量子比特索引映射（使用 {'all': 1} 展开全部）
param_show	bool	False	是否在输出中显示门参数值
with_logo	bool	False	是否在输出中包含 pyqpanda3 标志
line_length	int	100	文本输出每行最大字符数
output_file	str	''	保存输出的文件路径（空字符串表示输出到控制台）
encode	str	'utf-8'	输出文件的字符编码

返回值

str — 渲染后的线路图字符串。

示例

from pyqpanda3.core import draw_qprog, QProg, H, CNOT, PIC_TYPE

prog = QProg()
prog << H(0) << CNOT(0, 1)

# 以文本形式绘制（默认）
text_output = draw_qprog(prog)
print(text_output)

# 以 LaTeX 形式绘制
latex_output = draw_qprog(prog, PIC_TYPE.LATEX)

# 绘制时显示参数值
text_with_params = draw_qprog(prog, param_show=True)

# 保存到文件
draw_qprog(prog, output_file="circuit.txt")