构建量子线路 {#guide-circuit}¶

什么时候先看本页 {#guide-circuit-when-to-read}¶

当你还没把量子线路表达出来——还不确定如何用 uniqc.circuit_builder.Circuit 把一个量子算法或实验想法写成可执行的线路表示时，先看本页。

本页解决的核心问题是：如何从空线路开始，构建一个可以交给模拟器或真机的量子程序。

本页解决的问题 {#guide-circuit-problems}¶

如何创建空线路并添加量子门（uniqc.circuit_builder.Circuit）
如何添加测量指令
如何使用 CONTROL / DAGGER 控制结构
如何将线路导出为 OriginIR 或 OpenQASM 2.0 字符串
如何查看线路结构信息和做基础变换（重映射等）
如何提取线路的酉矩阵（Unitary Matrix）表示

基本用法¶

from uniqc import Circuit

circuit = Circuit()
circuit.h(0)
circuit.cnot(0, 1)
circuit.measure(0, 1)

量子门¶

单量子比特门¶

h, x, y, z, sx, s, t（无参数）

rx, ry, rz, p, u1（1 参数）, u2（2 参数）, u3（3 参数）, rphi

circuit.h(0)
circuit.rx(0, 0.5)    # RX 门，参数 0.5
circuit.p(0, 3.14)    # Phase 门（等价于 U1）
circuit.u3(0, 1.57, 0.785, 0.392)

双量子比特门¶

cnot, cx, cz, iswap, swap, crx, cry, crz, cp, cu, xx, yy, zz, phase2q, uu15

circuit.cnot(0, 1)
circuit.cz(1, 2)
circuit.crx(0, 1, 0.5)           # Controlled RX
circuit.cp(0, 1, 1.57)           # Controlled Phase
circuit.cu(0, 1, 1.57, 0.785, 0.392)  # Controlled U3

三量子比特门¶

toffoli, cswap

circuit.toffoli(0, 1, 2)

测量¶

circuit.measure(0, 1, 2)  # 测量指定量子比特

控制结构¶

CONTROL 块¶

with circuit.control(0, 1):
    circuit.x(2)

DAGGER 块¶

with circuit.dagger():
    circuit.h(0)
    circuit.cnot(0, 1)

格式互转 {#guide-circuit-format-conversion}¶

当你需要将线路提交到不同平台、交给不同后端执行，或与外部工具交换数据时，可以使用以下属性和方法导出/导入线路文本：

# 导出（属性形式）
originir_str = circuit.originir
qasm_str = circuit.qasm

# 导出（方法形式，推荐用于明确表达意图）
originir_str = circuit.to_originir()
qasm_str = circuit.to_qasm()
extended_originir_str = circuit.to_extended_originir()

# 从外部格式导入（类方法）
circuit_from_qasm = Circuit.from_qasm(qasm_str)
circuit_from_originir = Circuit.from_originir(originir_str)

关于 OriginIR 格式的详细说明，见 OriginIR。关于 QASM 格式与格式互转，见 QASM。

线路信息¶

Circuit 的几个常用统计量都通过 属性 (property) 暴露 —— 直接 circuit.depth 取值，不要写成 circuit.depth()（会得到 TypeError: 'int' object is not callable）。

circuit.depth        # 属性：线路深度（不计 I / BARRIER）
circuit.circuit      # 属性：完整线路字符串（含头和测量）
circuit.qubit_num    # 属性：量子比特数
circuit.cbit_num     # 属性：经典比特数
circuit.opcode_list  # 属性：门操作列表

如果需要按门类型 / 仅计算某些子集的深度，可使用底层函数 uniqc.compile.compute_gate_depth()，它接受一个 Circuit 并接受 virtual_z=True/False 等开关，返回与 Circuit.depth 同种类的整数指标。

量子比特重映射¶

# 将线路中的量子比特映射到新的索引
remapped = circuit.remapping({0: 3, 1: 5})

可视化¶

uniqc.compile.draw.draw() 用于绘制线路图：

from uniqc.compile.draw import draw

draw(circuit.originir)

可视化功能详见线路分析。

提取酉矩阵 {#guide-circuit-unitary-matrix}¶

对于不含测量门的线路，可以直接通过 Circuit.get_matrix()（或顶层 uniqc.get_matrix(circuit)）获取完整酉矩阵：

import numpy as np
from uniqc import Circuit, get_matrix

c = Circuit()
c.h(0)
c.cnot(0, 1)

U = c.get_matrix()       # 等价于 get_matrix(c)
print(U.shape)           # (4, 4)

约定：qubit 0 是 statevector 索引的最低位（little-endian），且 state_out = U @ state_in，门按 opcode_list 中的顺序左乘。

Note

若线路中包含 MEASURE / CONTROL / DAGGER 等无 unitary 表示的 opcode，会抛出 NotMatrixableError。如果只想看演化后的态矢，推荐使用状态向量模拟器：

from uniqc.simulator import Simulator
sim = Simulator(backend_type='statevector')
psi = sim.simulate_statevector(c.originir)

由于 get_matrix 显式构造 2**n × 2**n 矩阵，仅适合小规模（约 ≤ 12 qubit）线路。

命名量子寄存器 {#guide-circuit-named-qreg}¶

除了使用整数索引，还可以通过命名寄存器来组织量子比特。这在构建复杂电路时尤其有用。

创建带命名寄存器的电路¶

from uniqc import Circuit

# 创建带有两个命名寄存器的电路
c = Circuit(qregs={"data": 4, "ancilla": 2})

这会创建一个 6 量子比特的电路，其中 data 寄存器包含 4 个比特，ancilla 寄存器包含 2 个比特。

使用命名寄存器¶

# 获取寄存器引用
data = c.get_qreg("data")
ancilla = c.get_qreg("ancilla")

# 使用寄存器索引
c.h(data[0])           # 对 data[0] 应用 H 门
c.cnot(data[0], data[1])  # 对 data[0], data[1] 应用 CNOT

# 支持切片
c.x(data[1:3])         # 对 data[1], data[2] 应用 X 门

QReg 类型¶

QReg：命名量子寄存器，支持索引和切片
Qubit：单个量子比特的命名引用
QRegSlice：寄存器切片视图，用于多量子比特操作

参数化电路 {#guide-circuit-parametric}¶

UnifiedQuantum 支持符号化参数，可以在运行时绑定具体值。这对于变分算法（如 VQE、QAOA）非常有用。

创建参数¶

from uniqc import Parameter

# 创建命名参数
theta = Parameter("theta")
phi = Parameter("phi")

参数运算¶

参数支持算术运算，会自动创建符号表达式（基于 sympy）：

expr = theta * 2 + phi / 3

绑定和求值¶

# 绑定具体值
theta.bind(1.0)
phi.bind(0.5)

# 求值
value = theta.evaluate()  # 返回 1.0

# 或通过字典传入值（注意：当参数已绑定时，绑定值优先，dict 会被忽略）
result = theta.evaluate({"theta": 2.0})  # 仍返回 1.0
# 想让 dict 生效，先 unbind：
theta.unbind()
result = theta.evaluate({"theta": 2.0})  # 返回 2.0

在电路中使用参数¶

c = Circuit()
c.rx(0, theta)  # 参数化 RX 门
c.ry(1, phi)
c.measure(0, 1)

# 绑定参数后执行
theta.bind(0.5)
phi.bind(0.3)

参数数组¶

使用 Parameters 创建参数数组：

from uniqc import Parameters

# 创建 4 个参数：alpha_0, alpha_1, alpha_2, alpha_3
alphas = Parameters("alpha", size=4)

# 批量绑定
alphas.bind([0.1, 0.2, 0.3, 0.4])

# 索引访问
c.rx(0, alphas[0])

Named Circuit（可复用子程序） {#guide-circuit-named-circuit}¶

@circuit_def 装饰器用于定义可复用的量子子程序，类似 QASM3 的 gate 定义。

定义子程序¶

from uniqc import circuit_def, Circuit

@circuit_def(name="bell_pair", qregs={"q": 2})
def bell_pair(circ, q):
    circ.h(q[0])
    circ.cnot(q[0], q[1])
    return circ

应用子程序¶

# 创建父电路
c = Circuit(qregs={"data": 4})
data = c.get_qreg("data")

# 应用子程序，映射量子比特
bell_pair(c, qreg_mapping={"q": [data[0], data[1]]})

带参数的子程序¶

@circuit_def(name="rot_x", qregs={"q": 1}, params=["theta"])
def rot_x(circ, q, theta):
    circ.rx(q[0], theta)
    return circ

# 应用并传入参数
rot_x(c, qreg_mapping={"q": [data[2]]}, param_values={"theta": 0.5})

导出为 OriginIR DEF 块¶

# 导出子程序定义
def_block = bell_pair.to_originir_def()
print(def_block)
# DEF bell_pair(q[0], q[1])
#   H q[0]
#   CNOT q[0] q[1]
# ENDDEF

嵌套子程序¶

子程序可以调用其他子程序，构建层次化的电路结构：

@circuit_def(name="h_gate", qregs={"q": 1})
def h_gate(circ, q):
    circ.h(q[0])
    return circ

@circuit_def(name="h_all", qregs={"q": 4})
def h_all(circ, q):
    # 调用其他子程序
    for i in range(4):
        h_gate(circ, qreg_mapping={"q": [q[i]]})
    return circ

# 应用嵌套子程序
c = Circuit(4)
h_all(c, qreg_mapping={"q": [0, 1, 2, 3]})

独立构建电路¶

使用 build_standalone() 方法可以创建一个独立的电路实例：

# 直接构建独立电路
standalone = bell_pair.build_standalone()
print(standalone.originir)
# QINIT 2
# CREG 0
# H q[0]
# CNOT q[0], q[1]

# 带参数绑定构建
circuit = rot_x.build_standalone(param_values={"theta": 0.5})

子程序属性¶

NamedCircuit 对象提供以下属性：

print(bell_pair.name)           # "bell_pair"
print(bell_pair.qregs)          # {"q": 2}
print(bell_pair.params)         # []
print(bell_pair.num_qubits)     # 2
print(bell_pair.num_parameters) # 0

本页不重点解决的问题¶

本页聚焦于“如何把线路写出来”，以下问题不在本页展开：

模拟结果怎么看、如何选择本地模拟后端 → 见本地模拟
噪声模型与性能权衡 → 见噪声模拟
如何提交到真机或云平台 → 见提交任务

下一步¶

当你已经能生成 circuit.originir 或 circuit.qasm，且想在本地验证线路结果、比较不同模拟方式或做带噪声测试时，进入本地模拟。如果你已经完成本地验证，准备把线路提交到云平台或真机执行，则进入提交任务。