Qiskit 随机电路生成指南：random_circuit、random_circuit_from_graph 与 random_clifford_circuit 全面解析

• 科学计算

本文围绕 Qiskit 的qiskit.circuit.random模块展开，系统讲解如何利用该模块生成任意规模、任意形态的随机量子电路。随机电路是量子硬件基准测试（benchmarking）与转译器（transpiler）性能评估的标准工具，读完本文你将掌握random_circuit、random_circuit_from_graph、random_clifford_circuit三个生成器的完整参数语义、底层采样机制与可复现用法，可直接用于构建自己的基准测试管线。

模块定位：为什么需要随机电路

qiskit.circuit.random模块提供了一系列函数，用于生成门从给定门集合中随机选取的任意电路。根据 模块文档 的概述，这类电路有两个核心用途：

• 对现有量子硬件进行基准测试：随机电路的统计特性已知，便于评估硬件的保真度、串扰与噪声特性；
• 评估量子电路转译器与软件基础设施的性能：随机电路可以作为转译、调度、布局等 Pass 的压力测试输入，衡量时间开销与优化效果。

模块的公开 API 只有三个函数（定义于 qiskit/circuit/random/utils.py），覆盖三种生成场景：任意电路、尊重量子比特耦合约束的电路、纯 Clifford 电路：

三者均从qiskit.circuit.library.standard_gates的标准门集合中随机选取门，生成的均为QuantumCircuit对象。

random_circuit：生成任意形态的随机电路

random_circuit(num_qubits, depth, max_operands=4, measure=False, conditional=False, reset=False, seed=None, num_operand_distribution=None)是最通用的生成器，它按"层"（layer）组织门，depth即电路的关键路径长度（critical path length）。

参数语义

基本用法示例

模块文档中给出的最小示例（见 utils.py）：

from qiskit.circuit.random import random_circuit circ = random_circuit(2, 2, measure=True) circ.draw(output='mpl')

生成一个 2 量子比特、深度为 2、末尾带测量的随机电路。测试用例 test/python/circuit/test_random_circuit.py 验证了random_circuit(5, 4)得到的电路宽度为 5、深度恰为 4，说明depth语义是严格的分层（每层至少推进一个关键路径单位）。depth=0时返回空电路（宽度不变、深度为 0），见 测试第 38-42 行。

控制门操作数比例：num_operand_distribution

默认情况下，若不传num_operand_distribution，实现会先用rng.dirichlet(np.ones(max_operands))随机生成一个和为 1 的分布，再据此在每层中混合 1～max_operands比特门（utils.py）。若要精确控制比例，可显式传入分布字典，例如测试中的用法（测试第 96-99 行）：

circ = random_circuit( num_qubits=50, depth=300, num_operand_distribution={1: 0.25, 2: 0.25, 3: 0.25, 4: 0.25}, seed=123456789, )

该参数的约束与行为：

• 键必须介于 1～4 之间，否则抛出CircuitError（utils.py）；
• 键不能超过电路比特数（除非该键对应的权重为 0），否则抛出CircuitError（utils.py）；
• 所有值的和必须为 1（用np.isclose容差判断），否则抛出CircuitError（utils.py）；
• 权重为 0 的键对应比特数的门完全不会出现，可用于"只生成 2、3 比特门"这类定制，测试 第 108-126 行 与 第 150-168 行 对此有专门验证；
• 由于采样具有随机性，实际比例与目标比例存在偏差：电路比特数越少、深度越浅，偏差越大；比特数与深度越大，偏差越小（源码注释见 utils.py）。

底层分层算法要点

从源码（utils.py）可以看出实现的几个关键细节：

• 批量随机化：每层一次性用rng.choice抽取全部门的规格（类、比特数、参数个数），再用np.cumsum预计算量子比特索引与参数索引，最后用np.searchsorted找出能恰好用满不超过该层量子比特数量的门序列，避免了逐门调用随机数例程的性能开销；
• 余量（slack）填充：若一层内的门未用满全部比特，实现会在尊重num_operand_distribution的前提下，从大到小尝试补充门来填满余量（utils.py）；
• 参数采样：所有带参数门的参数值统一在[0, 2π)区间内均匀采样；
• conditional 语义：conditional=True时，从第 2 层开始每个门约有 10% 概率被包裹进qc.if_test条件块，且条件块之前会对全部比特做一次测量（utils.py）；条件值使用 Python 大整数（bigint）而非 NumPy 定宽类型，这是为保证条件语义正确性的刻意设计；
• reset：reset=True时，Reset操作会被加入 1 比特门候选集合（utils.py）。

random_circuit_from_graph：生成尊重耦合约束的随机电路

random_circuit_from_graph(interaction_graph, min_2q_gate_per_edge=1, max_operands=2, measure=False, conditional=False, reset=False, seed=None, insert_1q_oper=True, prob_conditional=0.1, prob_reset=0.1)面向需要严格贴合硬件拓扑（如 coupling map）的场景：生成的电路中，所有 2 比特门只出现在交互图允许的量子比特对上。

interaction_graph 的三种合法输入

交互图 G=(V, E)，其中 V 是电路中的量子比特，E 是允许发生双比特门交互的比特对集合。合法输入有两种形式：

1. rustworkx 图对象：rx.PyGraph或rx.PyDiGraph。节点的数量即电路比特数；每条边可以携带数值权重作为该比特对被选中的概率权重（源码通过interaction_graph.edges()读取边权重，见 utils.py）；
2. 元组列表：[(control_qubit, target_qubit, probability), ...]，等价于以列表形式直接描述图。比特数为列表中出现的最大索引 + 1（utils.py）。

传入其他对象（如 tuple 包装的列表）会抛出CircuitError，测试 第 562-566 行 专门覆盖了该分支。

边权重的概率语义

• 若所有边权重均为None（或图边不带权重），每条边以等概率1/N（N 为边数）被选中，即均匀抽取；
• 若所有边权重均为正数值，实现会先做归一化（若非 1 则除以总和），归一化后的权重即为各比特对被选中的概率；测试 第 493-560 行 验证了在足够大的电路中，各边实际出现频率与给定权重的偏差在 1% 以内；
• 权重为 0 的边会被直接排除，该比特对不会出现在输出电路中（utils.py），对应测试 第 338-359 行；
• 若部分权重为None而部分为数值（或存在负值），当max_operands=2时抛出ValueError（utils.py），对应测试 第 361-373 行 与 第 387-396 行。

核心参数与边界条件

生成循环逻辑（utils.py）：外层 while 循环持续运行，直到每条边都达到min_2q_gate_per_edge的使用次数；每轮迭代中按边权重抽样一批 2 比特门，应用到对应比特对，并记录使用次数；一轮结束后，仍未参与 2 比特门的空闲比特会被补上随机的 1 比特门（若insert_1q_oper=True）。测试 第 249-267 行 验证了每个比特对的使用次数都不少于min_2q_gate_per_edge。

边界与异常：

• max_operands不是 1 或 2 时抛出CircuitError（测试 第 375-385 行）；
• max_operands=1但insert_1q_oper=False时抛出CircuitError（无任何门可生成）；
• 交互图没有边、且insert_1q_oper=False时抛出CircuitError（utils.py）；
• max_operands=1或图中无边时，函数退化为调用random_circuit生成纯 1 比特门电路（utils.py）。

完整示例

模块文档中的示例（utils.py）演示了构造 PyDiGraph 并生成电路的全过程：

from qiskit.circuit.random.utils import random_circuit_from_graph import rustworkx as rx pydi_graph = rx.PyDiGraph() pydi_graph.add_nodes_from(range(7)) cp_map = [(0, 1, 0.18), (1, 2, 0.15), (2, 3, 0.15), (3, 4, 0.22), (4, 5, 0.13), (5, 6, 0.17)] pydi_graph.add_edges_from(cp_map) # cp_map 也可以直接作为 interaction_graph 传入 qc = random_circuit_from_graph(pydi_graph, min_2q_gate_per_edge=2, seed=12345) qc.draw(output='mpl')

测试中还覆盖了多种 rustworkx 生成图与列表输入（test_random_circuit.py）：环图、网格图、非完全图、heavy-hex 图、路径图、无边的空图，以及 20 条边的元组列表，验证了函数在稀疏/密集拓扑下的通用性。

random_clifford_circuit：生成伪随机 Clifford 电路

random_clifford_circuit(num_qubits, num_gates, gates="all", seed=None)用于生成由 Clifford 门构成的随机电路，常见于 Clifford 基准测试（如 randomized benchmarking 前的随机 Clifford 采样）。

门集合

默认gates="all"时，实现从 qiskit/quantum_info/operators/symplectic/clifford_circuits.py 定义的 Clifford 基门_BASIS_1Q/_BASIS_2Q中选取：1 比特门包括i、x、y、z、h、s、sdg、sx、sxdg（排除了语义重复的v、w、id、iden、sinv别名）；2 比特门包括cx、cy、cz、swap、iswap、ecr、dcx。若num_qubits=1，则只从 1 比特门中采样（utils.py）。

也可以传入自定义门名列表gates=["x", "h", "cx"]限定采样范围。每个门名到具体门对象与操作数的映射表定义在 utils.py。

用法与可复现性

from qiskit.circuit.random import random_clifford_circuit circ = random_clifford_circuit(num_qubits=2, num_gates=6) circ.draw(output='mpl')

seed参数有两种可接受类型（utils.py）：

• int：作为整数种子构造np.random.default_rng(seed)；
• np.random.Generator：直接复用调用方传入的随机数生成器，便于在长流程中串联随机性。

测试 test/python/quantum_info/operators/symplectic/test_clifford.py 验证了同一种子在不同PYTHONHASHSEED环境下的生成结果完全一致，说明函数输出的可复现性不依赖 Python 哈希随机化；该测试文件还大量使用random_clifford_circuit作为 Clifford 合成、转译等功能的随机输入来源。

随机性与可复现性约定

三个函数在随机性处理上保持一致：

• 所有随机数统一通过np.random.default_rng(seed)生成，传入相同整数种子即可获得完全相同的电路；
• seed=None时，实现自动取np.random.randint(0, np.iinfo(np.int32).max)作为种子（utils.py、utils.py），此时每次运行结果不同；
• 条件值（if_test的取值）特意转换为 Python 大整数，避免 NumPy 定宽整数类型造成条件语义偏差（见 utils.py 注释）。

在编写基准测试脚本时，务必传入固定seed以保证实验可复现、可对比；同时注意random_circuit的默认比例分布本身就是随机生成的（Dirichlet 采样），即使固定种子，不同调用之间门的比例结构也会随种子而变，需要精确控制时请显式指定num_operand_distribution。

与转译、QPY 等模块的联动

随机电路生成器在 Qiskit 生态中常作为其他功能的输入：

• 转译器压测：将生成的随机电路交给qiskit.compiler.transpiler的预设 PassManager 处理，可评估布局、路由与优化 Pass 的耗时与门数压缩效果；
• QPY 序列化：随机电路可被 qpy 格式 序列化与反序列化，用于验证格式兼容性（见 test/python/circuit/test_circuit_load_from_qpy.py）；
• Twirling 与错误表征：随机电路可作为基准注入到 twirling 等流程中（见 test/python/circuit/test_twirling.py）。

小结

qiskit.circuit.random用三个函数覆盖了随机电路生成的主要需求：random_circuit提供比特数、深度、操作数分布、条件/测量/reset 的全面控制，适合通用基准测试；random_circuit_from_graph以 rustworkx 图或边列表描述耦合约束并支持边权重概率，适合硬件拓扑感知的测试场景；random_clifford_circuit专门生成 Clifford 电路，服务 Clifford 相关的基准与验证需求。所有函数都支持固定种子复现，结合qiskit.converters.circuit_to_dag等工具即可搭建完整的随机电路基准测试管线。

• 科学计算