API 使用总览

本页是 UnitaryLab 模拟器的 API 入口导航，说明各模块的职责和推荐阅读路径。本页不是完整的 API Reference，函数签名和参数细节请查阅各章节文档。

推荐导入方式

from unitarylab import Circuit, Register, ClassicalRegister

Circuit 是所有操作的起点。unitarylab 包顶层只导出 Circuit、Register、ClassicalRegister 三个名称（from unitarylab.core import ... 是等价写法）；backend、circuit_analysis、drawer、transpiler、codegen 仅在调试、扩展或性能调优时才需直接使用。算法库 unitarylab.library 独立导出一批高层算法函数，见下文。

模块分层

unitarylab/
├── core/               # 用户入口层：Circuit、Register、ClassicalRegister
├── backend/            # 内部实现层：门结构、门序列、执行器、张量网络、QASM、底层门矩阵
├── transpiler/         # 线路转译：门基分解与优化规则
├── codegen/            # 线路 → Python 源码生成
├── circuit_analysis/   # 线路静态分析：CircuitInfo
├── drawer/             # 线路绘图：CircuitDrawer（mpl / text / latex）
└── library/            # 算法库：QFT、QPE、LCU、QSP、QSVT、块编码、哈密顿量模拟、线性方程组求解等

核心文档页面

核心线路接口

线路构建的完整参考，包括：

• 创建 Circuit，使用 Register / ClassicalRegister
• 单比特门（h、x、rx、rz 等，均支持一次对多个比特广播）、双比特门（cx、swap）
• 受控门（含多控制版本 mcx/mcy/mcz/mch/mcp/mcrx/mcry/mcrz）、自定义酉矩阵门、线路变换（inverse()、reverse()、repeat()、decompose()、control()、append()/prepend() 等）
• measure 操作和经典寄存器
• OpenQASM 2.0 / 3.0 与 Python 源码导入导出（to_qasm()、from_qasm()、to_python()）

线路执行与工具流程

执行线路及配套工具的综合参考，包括：

• Circuit.execute() 和 ExecutionResult（state、probabilities、expectation()、sample()、classical_results_map、counts）
• backend、device、dtype、shots、seed、backend_options 参数
• qc.draw() 绘图和 CircuitInfo / qc.analyze() 线路分析
• OpenQASM 导出（Circuit.to_qasm() / to_qasm2()）与导入（Circuit.from_qasm()）

算法与工具库

内置算法模块，包括：

以上 10 个名称是 unitarylab.library 包顶层直接导出的全部内容（即 library/__init__.py 的 __all__）。更底层的方法类（如 Trotter、QDrift、HHL、VQLS 等）需要从对应子模块导入，详见 算法与工具库。

推荐阅读顺序

1. 核心线路接口 — 构建线路
2. 线路执行与工具流程 — 执行、查看结果、分析、绘图、OpenQASM
3. 算法与工具库 — 算法应用