gpuqviz 0.5.0__py3-none-any.whl

gpuqviz/__init__.py

@@ -0,0 +1,45 @@
+"""gpuqviz: GPU-accelerated quantum state evolution visualization and video rendering."""
+
+__version__ = "0.5.0"
+
+from .api import render, render_bloch_video, render_frame, render_heatmap_video  # noqa: E401
+from .env import report_env  # noqa: E401
+from .export_html import export_html  # noqa: E401
+from .presets import (  # noqa: E401
+    PRESETS, RES_1080P, RES_1440P, RES_4K, RES_480P, RES_720P, RES_8K,
+    RES_SQUARE_1080, RES_SQUARE_2160, RES_VERTICAL_1080, RES_VERTICAL_720,
+)
+from .scene import TextOverlay, TextPosition  # noqa: E401
+from .scene import (Scene, BlochTrack, BlochVectorsTrack,  # noqa: E401
+                    DensityMatrixTrack, EntanglementTrack, HeatmapTrack,
+                    HistogramTrack, Camera)
+from .state import DensityMatrix, Statevector  # noqa: E401
+
+# 分析层子模块（专业轨道：测量统计 / 度量 / 纠缠，不依赖渲染）
+from . import analysis  # noqa: E401
+from .pro import ProReport, ProVisualizer  # noqa: E401
+
+# 算法库子模块（惰性加载，不依赖 qiskit/pyqpanda）
+from . import algorithms  # noqa: E401
+
+
+def show(*args, **kwargs):
+    """Jupyter 交互集成：notebook 中一行代码内嵌 3D 播放器。
+
+    惰性 import jupyter 模块，避免未装 IPython 时 import gpuqviz 失败。
+    """
+    from .jupyter import show as _show
+
+    return _show(*args, **kwargs)
+
+
+__all__ = ["__version__", "report_env", "render_bloch_video", "render_heatmap_video",
+           "render", "render_frame", "export_html", "show", "algorithms", "analysis",
+           "Statevector", "DensityMatrix",
+           "PRESETS", "RES_480P", "RES_720P", "RES_1080P", "RES_1440P",
+           "RES_4K", "RES_8K", "RES_SQUARE_1080", "RES_SQUARE_2160",
+           "RES_VERTICAL_720", "RES_VERTICAL_1080",
+           "TextOverlay", "TextPosition",
+           "Scene", "BlochTrack", "HeatmapTrack", "HistogramTrack",
+           "EntanglementTrack", "DensityMatrixTrack", "BlochVectorsTrack",
+           "Camera", "ProVisualizer", "ProReport"]

gpuqviz/adapters/__init__.py

@@ -0,0 +1,176 @@
+"""模拟器适配器：把第三方量子编程框架的电路接入 gpuqviz。
+
+- qiskit：evolve.sample_circuit（原生支持）；qiskit_to_gates 提供框架无关
+  的门级翻译（含 transpile 兜底），供 numpy 模拟器路径使用
+- pyqpanda：sample_pyqpanda（经 ORIGINIR 转换 + numpy 演化）
+
+pyqpanda 注意：transform_qprog_to_originir 必须使用与 prog 相同的 machine
+实例，跨 machine 转换会在原生层段错误（pyqpanda 2.x/3.x 已知行为），
+因此 machine 是必传参数，适配器绝不自建虚拟机。
+"""
+
+from __future__ import annotations
+
+import numpy as np
+
+# 命名门直译集合（其余门走矩阵路径 / definition 递归 / transpile 兜底）
+_NAMED_1Q = {"h", "x", "y", "z", "s", "sdg", "t", "tdg", "id", "i"}
+_NAMED_P = {"p", "u1", "u2", "u3", "u"}
+_NAMED_ROT = {"rx", "ry", "rz"}
+_TRANSPILE_BASIS = [
+    "id", "h", "x", "y", "z", "s", "sdg", "t", "tdg",
+    "rx", "ry", "rz", "u", "cx", "cy", "cz", "swap",
+]
+
+
+class _UnsupportedGate(Exception):
+    """门无法直译也无法取矩阵/展开时抛出，由上层触发 transpile 兜底。"""
+
+
+def _translate_op(op, qidx: list[int], depth: int = 0) -> list:
+    """单条 qiskit 指令 → Gate 列表。
+
+    优先级：命名直译 > to_matrix/Operator 矩阵 > definition 递归。
+    全局相位不影响 Bloch 向量与概率，统一忽略。
+    """
+    from ..circuits import Gate
+
+    if depth > 32:
+        raise _UnsupportedGate(f"definition nesting too deep: {op.name}")
+    name = op.name
+
+    # 命名门直译（保持 gate 语义可读，且覆盖 circuits.py 的命名分发路径）
+    if name in _NAMED_1Q:
+        return [Gate(name.upper(), targets=qidx)]
+    if name in _NAMED_ROT or name in _NAMED_P:
+        return [Gate(name.upper(), targets=qidx, params=list(op.params))]
+    if name in ("cx", "cnot"):
+        return [Gate("CX", targets=[qidx[1]], controls=[qidx[0]])]
+    if name in ("cy", "cz", "ch"):
+        return [Gate(name.upper(), targets=[qidx[1]], controls=[qidx[0]])]
+    if name == "swap":
+        return [Gate("SWAP", targets=qidx)]
+    if name == "iswap":
+        return [Gate("ISWAP", targets=qidx)]
+    if name == "ccx":
+        return [Gate("CCX", targets=[qidx[2]], controls=qidx[:2])]
+
+    # 受控门（CRX/MCX/CU/…）：直接取整门矩阵，qargs 顺序为 controls+targets
+    if getattr(op, "num_ctrl_qubits", 0):
+        try:
+            return [Gate("UNITARY", targets=qidx, matrix=_op_matrix(op))]
+        except Exception:
+            pass  # 落到 definition 递归
+
+    # 任意酉门（UnitaryGate、自定义 Gate、库门）：整门矩阵路径
+    try:
+        return [Gate("UNITARY", targets=qidx, matrix=_op_matrix(op))]
+    except Exception:
+        pass
+
+    # 复合门：递归展开 definition（子电路 qubit i 对应 qidx[i]）
+    defn = getattr(op, "definition", None)
+    if defn is not None and len(defn.data) > 0:
+        out = []
+        for sub in defn.data:
+            sub_q = [qidx[defn.find_bit(q).index] for q in sub.qubits]
+            out.extend(_translate_op(sub.operation, sub_q, depth + 1))
+        return out
+
+    raise _UnsupportedGate(f"cannot translate qiskit instruction: {name}")
+
+
+def _op_matrix(op) -> np.ndarray:
+    """qiskit Gate/Instruction → 2^k×2^k 酉矩阵（LSB = op 自身 qubit 0）。"""
+    try:
+        m = op.to_matrix()
+    except Exception:
+        from qiskit.quantum_info import Operator
+
+        m = Operator(op).to_matrix()
+    return np.asarray(m, dtype=np.complex128)
+
+
+def _translate_circuit(circuit) -> tuple[int, list]:
+    from ..circuits import Gate
+
+    n = circuit.num_qubits
+    gates: list = []
+    warned_measure = False
+    for inst in circuit.data:
+        op = inst.operation
+        qidx = [circuit.find_bit(q).index for q in inst.qubits]
+        if op.name in ("measure", "reset"):
+            # 态矢量演化不涉及测量/重置：按层边界处理，保证与可视化语义一致
+            if not warned_measure:
+                print("[gpuqviz] measure/reset 不会改变态矢量演化，按层边界处理")
+                warned_measure = True
+            gates.append(Gate("BARRIER"))
+            continue
+        if op.name == "delay":
+            continue
+        if op.name == "barrier":
+            gates.append(Gate("BARRIER"))
+            continue
+        gates.extend(_translate_op(op, qidx))
+    return n, gates
+
+
+def qiskit_to_gates(circuit) -> tuple[int, list]:
+    """qiskit QuantumCircuit → (n_qubits, Gate 列表)，框架无关路径的入口。
+
+    兜底策略：出现无法翻译的指令时，transpile 到基础门集后重试一次。
+    电路的末尾测量自动剔除；中途 measure/reset 按层边界处理。
+    """
+    circuit = circuit.remove_final_measurements(inplace=False)
+    try:
+        return _translate_circuit(circuit)
+    except _UnsupportedGate as e:
+        print(f"[gpuqviz] 直译失败（{e}），transpile 到基础门集后重试")
+        from qiskit import transpile
+
+        t = transpile(circuit, basis_gates=_TRANSPILE_BASIS,
+                      optimization_level=0)
+        return _translate_circuit(t)
+
+
+def sample_pyqpanda(prog, steps: int, machine) -> list[np.ndarray]:
+    """pyqpanda QProg → steps 个关键帧态矢量。
+
+    machine：创建 prog 时所用的量子虚拟机实例（必传，见模块 docstring）。
+    pyqpanda 为可选依赖，未安装时报错提示。
+    """
+    if machine is None:
+        raise TypeError(
+            "sample_pyqpanda requires the QVM instance that `prog` was built on "
+            "(machine=qm). Cross-machine ORIGINIR transforms segfault in pyqpanda.")
+    try:
+        from pyqpanda import transform_qprog_to_originir
+    except ImportError as e:  # pragma: no cover
+        raise ImportError(
+            "pyqpanda is required for pyqpanda circuits: pip install gpuqviz[pyqpanda]"
+        ) from e
+
+    from ..circuits import sample_originir
+
+    originir = transform_qprog_to_originir(prog, machine)
+    return sample_originir(originir, steps)
+
+
+def to_key_states(circuit, steps: int, machine=None) -> list[np.ndarray]:
+    """自动识别电路类型并采样关键帧。
+
+    qiskit QuantumCircuit 直接识别；pyqpanda QProg 需要同时传入
+    machine=（创建 prog 的虚拟机实例）。
+    """
+    # qiskit QuantumCircuit：num_qubits 属性 + data 指令列表
+    if hasattr(circuit, "num_qubits") and hasattr(circuit, "data"):
+        from ..evolve import sample_circuit
+
+        return sample_circuit(circuit, steps)
+    if machine is not None:
+        return sample_pyqpanda(circuit, steps, machine)
+    raise TypeError(
+        f"unsupported circuit type {type(circuit).__name__}: expected a qiskit "
+        "QuantumCircuit, or a pyqpanda QProg together with machine=<QVM instance>"
+    )

gpuqviz/algorithms/__init__.py

@@ -0,0 +1,118 @@
+"""gpuqviz 内置量子算法库。
+
+每个算法函数按 ``engine`` 参数返回对应类型的电路对象：
+- ``"qiskit"``（默认）：返回 ``qiskit.QuantumCircuit``
+- ``"pyqpanda"``：返回 ``pyqpanda.QProg``（需配合 machine）
+- ``"numpy"``：返回 ``list[Gate]``（框架无关）
+
+返回的电路对象可直接传入 ``render_bloch_video`` / ``export_html`` / ``show``
+等可视化 API，或经 ``evolve_gates`` 做纯 numpy 演化。
+
+用法::
+
+    from gpuqviz.algorithms import grover, bell, qft
+
+    qc = grover(n=3, marked=0b101, iterations=2)
+    gpuqviz.export_html(circuit=qc, out="out/grover.html")
+
+    # numpy 路径（无 qiskit 依赖）
+    gates = grover(n=3, engine="numpy")
+    from gpuqviz.circuits import evolve_gates
+    states = evolve_gates(3, gates)
+
+CLI 一行命令::
+
+    gpuqviz demo --algo grover
+    gpuqviz demo --algo qft --format mp4
+    gpuqviz demo --list
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Callable
+
+from ._primitive import bell, ghz, superposition
+from ._grover import grover
+from ._qft import qft
+from ._qpe import phase_estimation
+from ._deutsch_jozsa import deutsch_jozsa
+from ._bernstein_vazirani import bernstein_vazirani
+from ._teleportation import teleportation
+from ._superdense import superdense
+from ._simon import simon
+from ._quantum_walk import quantum_walk
+
+__all__ = [
+    "bell", "ghz", "superposition", "grover", "qft", "phase_estimation",
+    "deutsch_jozsa", "bernstein_vazirani", "teleportation", "superdense",
+    "simon", "quantum_walk",
+    "ALGORITHM_REGISTRY", "AlgorithmSpec", "get_algorithm", "list_algorithms",
+]
+
+
+@dataclass
+class AlgorithmSpec:
+    """算法注册表条目。"""
+    name: str
+    description: str
+    builder: Callable[..., Any]
+    default_n_qubits: int
+    category: str
+
+
+# 算法注册表：name → spec
+ALGORITHM_REGISTRY: dict[str, AlgorithmSpec] = {
+    "bell": AlgorithmSpec(
+        "bell", "Bell 态 |Φ+⟩ = (|00⟩+|11⟩)/√2 制备", bell, 2, "基础态"),
+    "ghz": AlgorithmSpec(
+        "ghz", "n 量子比特 GHZ 纠缠态 (|0…0⟩+|1…1⟩)/√2", ghz, 3, "基础态"),
+    "superposition": AlgorithmSpec(
+        "superposition", "均匀叠加态 H^n |0…0⟩ = |+⟩^n", superposition, 3, "基础态"),
+    "grover": AlgorithmSpec(
+        "grover", "Grover 搜索算法（振幅放大）", grover, 3, "搜索"),
+    "qft": AlgorithmSpec(
+        "qft", "量子傅里叶变换", qft, 3, "变换"),
+    "phase_estimation": AlgorithmSpec(
+        "phase_estimation", "量子相位估计（QPE）", phase_estimation, 4, "估计"),
+    "deutsch_jozsa": AlgorithmSpec(
+        "deutsch_jozsa", "Deutsch-Jozsa 算法（常数 vs 平衡判定）",
+        deutsch_jozsa, 4, "查询复杂度"),
+    "bernstein_vazirani": AlgorithmSpec(
+        "bernstein_vazirani", "Bernstein-Vazirani 算法（恢复隐藏字符串）",
+        bernstein_vazirani, 3, "查询复杂度"),
+    "teleportation": AlgorithmSpec(
+        "teleportation", "量子隐形传态（3 qubit Bell pair + 经典校正）",
+        teleportation, 3, "通信"),
+    "superdense": AlgorithmSpec(
+        "superdense", "超密编码（1 qubit 传 2 经典比特）",
+        superdense, 2, "通信"),
+    "simon": AlgorithmSpec(
+        "simon", "Simon 算法（寻找 2-to-1 函数的隐藏周期）",
+        simon, 4, "查询复杂度"),
+    "quantum_walk": AlgorithmSpec(
+        "quantum_walk", "离散时间量子随机游走（硬币 + 条件移位）",
+        quantum_walk, 3, "游走"),
+}
+
+
+def get_algorithm(name: str) -> AlgorithmSpec:
+    """按名称获取算法注册表条目。不存在时抛 KeyError。"""
+    if name not in ALGORITHM_REGISTRY:
+        raise KeyError(
+            f"unknown algorithm {name!r}; available: {sorted(ALGORITHM_REGISTRY)}"
+        )
+    return ALGORITHM_REGISTRY[name]
+
+
+def list_algorithms() -> str:
+    """返回格式化的算法列表字符串（供 CLI --list 输出）。"""
+    lines = [
+        f"{'名称':<25} {'类别':<12} {'默认qubit':<10} {'说明'}",
+        f"{'─' * 25} {'─' * 12} {'─' * 10} {'─' * 40}",
+    ]
+    for spec in ALGORITHM_REGISTRY.values():
+        lines.append(
+            f"{spec.name:<25} {spec.category:<12} {spec.default_n_qubits:<10} {spec.description}"
+        )
+    return "\n".join(lines)

gpuqviz/algorithms/_bernstein_vazirani.py

@@ -0,0 +1,71 @@
+"""Bernstein-Vazirani 算法电路构建器。
+
+给定一个隐藏字符串 s ∈ {0,1}^n 和函数 f(x) = s · x (mod 2)，
+BV 算法用一次量子查询恢复 s。
+
+电路结构：
+1. 辅助 qubit |1⟩ → H
+2. 输入寄存器 H(all)
+3. Oracle Uf：对每个 s_i = 1 的 qubit 做 CX(i, aux)
+4. 输入寄存器 H(all)
+5. 测量输入寄存器 → 得到 |s⟩
+"""
+
+from __future__ import annotations
+
+from ._engine import (
+    _check_engine,
+    _numpy_gates_to_circuit,
+    _qiskit_circuit,
+)
+from ..circuits import Gate
+
+
+def bernstein_vazirani(secret: str = "101", engine: str = "qiskit"):
+    """Bernstein-Vazirani 算法电路。
+
+    Parameters
+    ----------
+    secret : str
+        隐藏比特串，如 "101"（长度 = n）。从左到右对应 q0, q1, …, q_{n-1}。
+    engine : str
+        "qiskit" / "numpy"。
+    """
+    engine = _check_engine(engine)
+    # secret 字符串："101" → s[0]='1', s[1]='0', s[2]='1'
+    # qubit i 对应 secret[i]
+    n = len(secret)
+    if n < 1:
+        raise ValueError(f"secret must be non-empty, got {secret!r}")
+    bits = [int(c) for c in secret if c in "01"]
+    if len(bits) != n:
+        raise ValueError(f"secret must be binary string, got {secret!r}")
+
+    n_total = n + 1
+    aux = n
+
+    if engine == "qiskit":
+        qc = _qiskit_circuit(n_total)
+        qc.x(aux)
+        qc.h(range(n_total))
+        # Oracle：s_i = 1 时 CX(i, aux)
+        for i in range(n):
+            if bits[i]:
+                qc.cx(i, aux)
+        qc.h(range(n))
+        return qc
+
+    if engine == "pyqpanda":
+        raise NotImplementedError("use bernstein_vazirani_pyqpanda(qubits, machine, ...)")
+
+    # numpy 路径
+    gates: list[Gate] = []
+    gates.append(Gate("X", targets=[aux]))
+    for i in range(n_total):
+        gates.append(Gate("H", targets=[i]))
+    for i in range(n):
+        if bits[i]:
+            gates.append(Gate("CX", targets=[aux], controls=[i]))
+    for i in range(n):
+        gates.append(Gate("H", targets=[i]))
+    return _numpy_gates_to_circuit(gates)

gpuqviz/algorithms/_deutsch_jozsa.py

@@ -0,0 +1,90 @@
+"""Deutsch-Jozsa 算法电路构建器。
+
+判断函数 f: {0,1}^n → {0,1} 是常数（所有输出相同）还是平衡（一半 0 一半 1）。
+
+电路结构：
+1. 辅助 qubit |1⟩ → H
+2. 输入寄存器 H(all)
+3. Oracle Uf（常数/平衡两种）
+4. 输入寄存器 H(all)
+5. 测量输入寄存器：全 0 = 常数，否则 = 平衡
+"""
+
+from __future__ import annotations
+
+from ._engine import (
+    _check_engine,
+    _numpy_gates_to_circuit,
+    _qiskit_circuit,
+)
+from ..circuits import Gate
+
+
+def _build_balanced_oracle_qiskit(qc, n: int):
+    """平衡 oracle：f(x) = x_0（第一个 qubit 的值）。
+    用 CX(0, aux) 实现：aux ^= x_0。
+    """
+    aux = n  # 辅助 qubit 索引
+    qc.cx(0, aux)
+
+
+def _build_constant_oracle_qiskit(qc, n: int):
+    """常数 oracle：f(x) = 0（不做任何操作）或 f(x) = 1（翻转 aux）。
+    这里用 f(x) = 1：X(aux)。
+    """
+    aux = n
+    qc.x(aux)
+
+
+def deutsch_jozsa(oracle_type: str = "balanced", n: int = 3,
+                  engine: str = "qiskit"):
+    """Deutsch-Jozsa 算法电路。
+
+    Parameters
+    ----------
+    oracle_type : str
+        "balanced" 或 "constant"。
+    n : int
+        输入寄存器量子比特数（总 qubit = n + 1 辅助）。
+    engine : str
+        "qiskit" / "numpy"。
+    """
+    engine = _check_engine(engine)
+    if oracle_type not in ("balanced", "constant"):
+        raise ValueError(f"oracle_type must be 'balanced' or 'constant', got {oracle_type!r}")
+    if n < 1:
+        raise ValueError(f"n must be >= 1, got {n}")
+
+    n_total = n + 1
+    aux = n
+
+    if engine == "qiskit":
+        qc = _qiskit_circuit(n_total)
+        # 辅助 qubit |1⟩
+        qc.x(aux)
+        # 全部 H
+        qc.h(range(n_total))
+        # Oracle
+        if oracle_type == "balanced":
+            _build_balanced_oracle_qiskit(qc, n)
+        else:
+            _build_constant_oracle_qiskit(qc, n)
+        # 输入寄存器 H
+        qc.h(range(n))
+        return qc
+
+    if engine == "pyqpanda":
+        raise NotImplementedError("use deutsch_jozsa_pyqpanda(qubits, machine, ...)")
+
+    # numpy 路径
+    gates: list[Gate] = []
+    gates.append(Gate("X", targets=[aux]))
+    for i in range(n_total):
+        gates.append(Gate("H", targets=[i]))
+    if oracle_type == "balanced":
+        gates.append(Gate("CX", targets=[aux], controls=[0]))
+    else:
+        gates.append(Gate("X", targets=[aux]))
+    for i in range(n):
+        gates.append(Gate("H", targets=[i]))
+    return _numpy_gates_to_circuit(gates)

gpuqviz/algorithms/_engine.py

@@ -0,0 +1,95 @@
+"""引擎抽象层：算法函数按 engine 参数返回对应类型的电路对象。
+
+三种引擎：
+- qiskit（默认）：返回 qiskit.QuantumCircuit
+- pyqpanda：返回 pyqpanda.QProg（需调用方传入 machine）
+- numpy：返回 list[Gate]（框架无关，纯 numpy 演化）
+
+每个算法构建函数在内部按 engine 分发，算法逻辑不变。
+"""
+
+from __future__ import annotations
+
+
+
+from ..circuits import Gate
+
+ENGINE_QISKIT = "qiskit"
+ENGINE_PYQPANDA = "pyqpanda"
+ENGINE_NUMPY = "numpy"
+_VALID_ENGINES = {ENGINE_QISKIT, ENGINE_PYQPANDA, ENGINE_NUMPY}
+
+
+def _check_engine(engine: str) -> str:
+    if engine not in _VALID_ENGINES:
+        raise ValueError(
+            f"unsupported engine {engine!r}; expected one of {sorted(_VALID_ENGINES)}"
+        )
+    return engine
+
+
+# --------------------------------------------------------------------------- #
+# qiskit 构建辅助
+# --------------------------------------------------------------------------- #
+
+def _qiskit_circuit(n_qubits: int):
+    """创建 qiskit QuantumCircuit（惰性 import qiskit）。"""
+    from qiskit import QuantumCircuit
+
+    return QuantumCircuit(n_qubits)
+
+
+# --------------------------------------------------------------------------- #
+# pyqpanda 构建辅助
+# --------------------------------------------------------------------------- #
+
+def _pyqpanda_prog():
+    """创建 pyqpanda QProg（惰性 import）。"""
+    from pyqpanda import QProg
+
+    return QProg()
+
+
+def _pyqpanda_gate(prog, name: str, qubits: list, params: list[float] | None = None,
+                   controls: list | None = None):
+    """向 QProg 追加一个门。qubits 是已分配的 pyqpanda qubit 引用列表。"""
+    import pyqpanda as pq
+
+    name = name.upper()
+    if name == "H":
+        prog << pq.H(qubits[0])
+    elif name == "X":
+        prog << pq.X(qubits[0])
+    elif name == "Y":
+        prog << pq.Y(qubits[0])
+    elif name == "Z":
+        prog << pq.Z(qubits[0])
+    elif name == "S":
+        prog << pq.S(qubits[0])
+    elif name == "T":
+        prog << pq.T(qubits[0])
+    elif name == "RX":
+        prog << pq.RX(qubits[0], params[0])
+    elif name == "RY":
+        prog << pq.RY(qubits[0], params[0])
+    elif name == "RZ":
+        prog << pq.RZ(qubits[0], params[0])
+    elif name in ("CX", "CNOT"):
+        prog << pq.CNOT(qubits[0], qubits[1])
+    elif name == "CZ":
+        prog << pq.CZ(qubits[0], qubits[1])
+    elif name == "SWAP":
+        prog << pq.SWAP(qubits[0], qubits[1])
+    elif name in ("CCX", "TOFFOLI"):
+        prog << pq.Toffoli(qubits[0], qubits[1], qubits[2])
+    else:
+        raise ValueError(f"pyqpanda does not support gate {name}")
+
+
+# --------------------------------------------------------------------------- #
+# numpy 构建辅助
+# --------------------------------------------------------------------------- #
+
+def _numpy_gates_to_circuit(gates: list[Gate]) -> list[Gate]:
+    """numpy 路径直接返回 Gate 列表。"""
+    return list(gates)