docs: update documentation

docs/Makefile

@@ -0,0 +1,15 @@
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= python -m sphinx
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+.PHONY: help html clean
+
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS)
+
+html:
+	@$(SPHINXBUILD) -M html "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS)
+
+clean:
+	@$(SPHINXBUILD) -M clean "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS)

docs/conf.py

@@ -0,0 +1,32 @@
+project = "Cqlib"
+author = "Cqlib contributors"
+copyright = "2026, Cqlib contributors"
+
+from pygments.lexers.special import TextLexer
+from sphinx.highlighting import lexers
+
+extensions = [
+    "myst_parser",
+]
+
+source_suffix = {
+    ".rst": "restructuredtext",
+    ".md": "markdown",
+}
+
+root_doc = "index"
+language = "zh_CN"
+
+exclude_patterns = [
+    "_build",
+    "Thumbs.db",
+    ".DS_Store",
+]
+
+html_theme = "classic"
+html_title = "Cqlib 文档"
+html_show_sourcelink = False
+
+myst_heading_anchors = 3
+
+lexers["mermaid"] = TextLexer()

docs/documentation/0_get_started/0_introduction.md

@@ -0,0 +1,74 @@
+# Cqlib 简介
+
+## 欢迎使用 Cqlib！
+
+Cqlib 是由中电信量子集团自主研发、专为工程实践打造的量子计算软件开发工具包（SDK）。依托[“天衍”量子计算云平台](https://qc.zdxlz.com)，Cqlib 提供了统一、稳定、高性能的量子线路编程接口与表示能力，实现真机算力接入与高效模拟计算服务的无缝转换。
+
+本套说明文档涵盖[安装教程](1_installation.md)、[快速入门](2_quickstart.md)、[场景化指南](../1_cqlib/0_circuit/0_overview.md)及多种编程语言的 [API 参考](../../api/python/0_overview.md)，致力于帮助您更顺畅地完成量子计算任务的构建、执行与可视化，全面提升开发效率与使用体验。
+
+---
+
+
+## 为什么选择 Cqlib ？
+
+- **极致性能，Rust 驱动**  
+  核心层采用 Rust 语言构建，确保[线路编译](../1_cqlib/5_transpilation/0_overview.md)与[中间表示](../1_cqlib/1_ir/0_overview.md)转换的高并发处理能力与内存安全性，为大规模量子线路模拟与复杂逻辑处理提供坚实底座。
+
+- **原生生态，天衍直连**  
+  深度集成国产自主量子指令集 [QCIS](../1_cqlib/1_ir/1_qcis.md)，并与 [“天衍”量子计算云平台](https://qc.zdxlz.com) 无缝衔接，支持从本地开发到云端执行的灵活迁移。
+
+- **多语协同，开发友好**  
+  通过高度抽象的 [Python 接口](../../api/python/0_overview.md)与底层 [C 接口](../../api/c/0_overview.md)协同设计，兼顾算法研发效率与系统集成稳定性，支持跨平台、跨语言的混合编程场景。
+
+- **统一架构，灵活扩展**  
+  提供统一的[中间表示](../1_cqlib/1_ir/0_overview.md)，支持构建可维护、可扩展的量子软件系统，适配从原型验证到企业级应用开发的完整流程。
+
+---
+
+## Cqlib 采用什么编程语言？
+
+Cqlib 采用 Rust、Python 和 C 三种语言，整体遵循“核心统一、接口分层”的设计思路，在保证能力一致性的同时兼顾不同开发场景的使用习惯：
+
+- **[Rust](../../api/rust/0_overview.md)**  
+  作为核心实现层，承载量子线路、门与指令、参数系统、中间表示、设备建模、量子信息、错误缓解和编译优化等关键能力。
+
+- **[Python](../../api/python/0_overview.md)**  
+  面向算法开发与快速原型验证，提供更高效、直观的 Python 接口，便于交互式使用和快速迭代。
+
+- **[C](../../api/c/0_overview.md)**  
+  面向系统集成与跨语言调用，提供稳定的 C 接口，便于在异构工程中落地部署。
+
+---
+
+## Cqlib 能做什么？
+
+Cqlib 的核心能力主要由以下八个模块组成：
+
+- [量子线路](../1_cqlib/0_circuit/0_overview.md)
+  用于创建和管理量子线路，支持量子门添加、参数化线路、控制流、线路组合、矩阵转换和结构分析等基础功能，是使用 Cqlib 构建量子程序的主要入口。
+- [中间表达](../1_cqlib/1_ir/0_overview.md)
+  用于在线路对象和文本格式之间进行转换，支持 QCIS、OpenQASM 2.0 和 OpenQASM 3.0 格式，便于线路保存、跨工具链交换以及后续编译处理。
+- [设备模块](../1_cqlib/2_device/0_overview.md)
+  用于描述量子设备相关信息，包括设备拓扑、逻辑比特到物理比特的映射、校准属性、噪声模型和执行结果等，为后端适配和噪声感知编译提供数据基础。
+- [量子信息](../1_cqlib/3_qis/0_overview.md)
+  提供量子态、算符和量子信息处理相关工具，包括状态向量、密度矩阵、稳定子模拟、Pauli 算符、哈密顿量、量子演化和信息度量等能力。
+- [编译优化](../1_cqlib/4_compiler/0_overview.md)
+  用于将高层量子线路转换为更适合目标设备执行的线路形式，支持门分解、拓扑布局、路由映射、模板匹配、交换优化和 Clifford 相关优化等功能。
+- [可视化](../1_cqlib/5_visualization/0_overview.md)
+  用于展示量子线路结构，支持 Unicode 文本图和 SVG 图形渲染，便于用户查看线路层次、门操作顺序和整体结构。
+- [错误缓解](../1_cqlib/6_error_mitigation/0_overview.md)
+  用于降低噪声对量子计算结果的影响，提供零噪声外推和虚拟蒸馏等错误缓解能力，适合在含噪模拟或真实设备实验结果处理中使用。
+- [天衍量子云平台客户端](../1_cqlib/7_tianyan/0_overview.md)
+  用于连接天衍量子云平台，支持平台认证、后端查询、设备配置获取、QCIS 任务提交、任务状态轮询、执行结果解析和读取误差矫正等能力，适合将本地构建的线路提交到云端真实设备或平台后端执行。
+
+---
+
+
+## 下一步
+
+如果您准备开始使用 Cqlib，建议按照以下顺序继续阅读：
+
+- [安装指南](1_installation.md)：安装配置一键搞定
+- [快速开始](2_quickstart.md)：从“0”到“1”的第一个量子线路
+- [量子线路](../1_cqlib/0_circuit/0_overview.md)：了解 Cqlib 中描述量子程序的基础模块。
+- [天衍量子云平台客户端](../1_cqlib/7_tianyan/0_overview.md)：了解如何登录平台、选择后端、提交 QCIS 任务并获取云端执行结果。

docs/documentation/0_get_started/1_installation.md

@@ -0,0 +1,143 @@
+# Cqlib 安装与环境配置
+
+本指南旨在帮助您快速完成 Cqlib 的安装与开发环境配置。
+
+在安装 Cqlib 之前，请确保您的计算机环境满足以下条件：
+
+- Python 环境：支持 Python 3.10 – 3.14（建议使用 64 位版本）；
+- 操作系统：
+  - Linux
+  - macOS
+  - Windows
+
+---
+
+## 方式 A：通过 `pip` 快速安装（推荐）
+
+对于大多数用户，推荐使用 `pip` 直接安装。
+
+
+> 适用场景：算法研发、原型验证。  
+> 注意事项：此方式已包含预编译二进制文件，无需安装 Rust 或 C 编译器。
+
+### 第一步：创建并激活虚拟环境
+
+建议在独立的环境中进行操作，以避免依赖冲突：
+
+```bash
+python -m venv cqlib-env
+
+# 激活环境 (Windows)
+cqlib-env\Scripts\activate
+# 激活环境 (Linux/macOS)
+source cqlib-env/bin/activate
+```
+
+### 第二步：`pip` 一键安装
+
+```bash
+pip install cqlib
+```
+
+### 第三步：安装验证
+
+安装完成后，可以通过以下方式验证：
+
+```python
+import cqlib
+print(cqlib.__version__)
+```
+如果能够正确输出版本号，则说明安装成功。
+
+---
+
+## 方式 B：从源码构建（面向开发者）
+
+如果您希望参与 Cqlib 的开发，或使用尚未发布的最新功能，可以使用下列方法从源码构建。
+
+> 适用场景：定制化开发、贡献代码或使用最新特性。
+> 注意事项：此方式要求本地具备编译环境。
+
+### 第一步：配置编译链工具
+
+在构建前，请根据您的操作系统安装以下必要组件：
+
+- 安装 Rust 工具链（Stable 1.85+）：
+
+  - Windows：访问官方网站： https://www.rust-lang.org/tools/install 下载并运行安装程序。
+  - Linux/macOS：执行 `curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh`
+
+- 安装 C 编译器：
+  - Windows：安装 Visual Studio 生成工具，并勾选“使用 C++ 的桌面开发”。
+  - Linux：安装 `build-essential`（Ubuntu/Debian）或 `base-devel`（Arch）。
+  - macOS：终端执行 `xcode-select --install`。
+
+安装完成后，可通过以下命令验证：
+
+```bash
+rustc --version
+cargo --version
+```
+如果能够正确输出版本号，则说明 Rust 安装成功。
+
+### 第二步：获取源代码
+
+从 Gitee 克隆仓库到本地：
+```bash
+git clone https://gitee.com/zdxlz/cqlib2.git
+cd cqlib
+```
+
+### 第三步：编译并安装 Python 绑定
+
+我们使用 `maturin` 跨语言工具将 Rust 核心编译为 Python 模块：
+
+```bash
+# 1. 安装构建工具
+pip install -U maturin
+
+# 2. 编译并安装到当前环境
+# --release 参数可确保获得最佳运行性能
+maturin develop --release -m crates/binding-python/Cargo.toml
+```
+该命令将在当前虚拟环境中安装本地构建版本。
+
+### 第四步：构建 Rust 核心与 C 接口（可选）
+
+```bash
+# 构建核心库
+cargo build --release
+
+# 构建 C 接口 ABI（可选）
+cargo build -p binding-c --release
+```
+
+---
+
+## 可选模块：安装天衍量子云平台客户端
+
+如果需要将本地线路提交到天衍量子云平台执行，还需要安装 `cqlib-tianyan`。该模块独立于 Cqlib 核心包，主要负责平台认证、后端查询、任务提交、任务轮询和结果解析。
+
+```bash
+pip install cqlib-tianyan
+```
+
+安装后可通过以下方式验证：
+
+```python
+from cqlib_tianyan import TianyanPlatform
+print(TianyanPlatform)
+```
+
+`cqlib-tianyan` 通常与 `cqlib` 配合使用：先用 `cqlib.circuit` 构建线路，再用 `cqlib.ir.qcis` 导出 QCIS，最后通过 `cqlib_tianyan` 提交到云端后端。
+
+---
+
+## 下一步
+
+安装完成后，建议继续阅读以下内容：
+
+- [快速开始](2_quickstart.md)：从“0”到“1”的第一个量子线路
+- [量子线路](../1_cqlib/0_circuit/0_overview.md)：了解 Cqlib 中描述量子程序的基础模块。
+- [量子门与指令](../1_cqlib/0_circuit/1_gates.md)：了解内置门、自定义门、复合门和非酉指令。
+- [天衍量子云平台客户端](../1_cqlib/7_tianyan/0_overview.md)：了解云端后端接入、任务提交和结果获取流程。

docs/documentation/0_get_started/2_quickstart.md

@@ -0,0 +1,122 @@
+# 快速开始
+
+本指南将带您使用 Cqlib 构建一个最小可用的量子线路，并完成一次端到端的“工程闭环”流程。
+
+在开始之前，请确保您的环境已准备就绪：
+
+- Python 环境：支持 Python 3.10 – 3.14
+- 完成 Cqlib 安装与环境配置（安装方式见 “[Cqlib 安装与环境配置](../0_get_started/1_installation.md)”）
+
+---
+
+## 第一个量子线路：Bell 态
+
+本节通过一个最小但完整的 Bell 态示例，介绍 Cqlib 构建量子线路的基本流程。通过该示例，您将了解如何创建线路、添加量子门、查看线路结构，并进一步进行状态模拟、测量采样、线路可视化和 IR 导出等操作。
+
+Bell 态是量子计算中最常见的双比特纠缠态之一，通常用于演示叠加与纠缠的基本概念。构造 Bell 态需要以下两个步骤：
+
+- 对第 `0` 个量子比特施加 `H` 门，使其进入叠加态；
+- 以第 `0` 个量子比特为控制比特、第 `1` 个量子比特为目标比特施加 CX 门，从而在两个量子比特之间建立纠缠关系。
+
+理想情况下，最终得到的量子态为：
+
+```text
+(|00> + |11>) / sqrt(2)
+```
+
+## 1. 创建线路
+
+首先创建一条两比特量子线路，并向其中依次添加 `H` 门和 `CX` 门：
+
+```python
+from cqlib import Circuit
+
+circuit = Circuit(2)
+circuit.h(0)
+circuit.cx(0, 1)
+
+print(circuit.num_qubits)   # 2
+print(len(circuit))         # 2
+print(circuit.operations)   # 查看底层 Operation 列表
+```
+
+## 2. 使用文本图查看线路
+
+将量子线路渲染为文本图以查看线路结构：
+
+```python
+from cqlib.visualization import draw_text
+
+print(draw_text(circuit))
+```
+
+## 3. 转为矩阵验证
+
+对于小规模纯量子门线路，可以将整条线路转换为完整酉矩阵，用于验证线路的数学行为：
+
+```python
+matrix = circuit.to_matrix()
+print(matrix)
+```
+
+## 4. 导出 OpenQASM 2.0 / 3.0
+
+此外，Cqlib 还提供了 OpenQASM 2.0 和 OpenQASM 3.0 的导出接口：
+
+```python
+from cqlib.ir import qasm2, qasm3
+
+print(qasm2.dumps(circuit))
+print(qasm3.dumps(circuit))
+```
+
+## 5. 状态向量模拟
+
+使用状态向量模拟来查看线路作用后的量子态分布：
+
+```python
+from cqlib.qis import Statevector
+
+sv = Statevector.from_circuit(circuit)
+print(sv.data)
+print(sv.probabilities())
+```
+
+对于 Bell 态线路，理想情况下，`probabilities()` 的结果应接近：
+
+```text
+[0.5, 0.0, 0.0, 0.5]
+```
+
+这表示测量时只会得到 `00` 和 `11` 两种结果，并且二者概率相同；而 `01` 和 `10` 的概率接近 `0`，这体现了 Bell 态中两个量子比特之间的纠缠关联。
+
+## 6. 采样测量
+
+得到状态向量后，可以进一步进行多次采样，模拟实际测量过程中的统计结果：
+
+```python
+shots = sv.sample_shots(1000)
+counts = {}
+for outcome in shots:
+    bitstring = outcome.to_bitstring(2)
+    counts[bitstring] = counts.get(bitstring, 0) + 1
+
+print(counts)
+```
+
+输出结果类似：
+
+```text
+{'00': 506, '11': 494}
+```
+
+由于采样过程具有随机性，每次运行得到的计数结果不会完全相同。但对于理想 Bell 态，大量采样后，`00` 和 `11` 的出现次数应大致相近，而 `01` 和 `10` 通常不会出现或概率接近于零。
+
+---
+
+## 下一步
+
+- [量子线路](../1_cqlib/0_circuit/0_overview.md)：了解 Cqlib 中描述量子程序的基础模块。
+- [量子门与指令](../1_cqlib/0_circuit/1_gates.md)：了解内置门、自定义门、复合门和非酉指令。
+- [线路结构与构造](../1_cqlib/0_circuit/2_structures.md)：掌握 `Circuit` 的生命周期、索引、组合和操作表示。
+- [天衍量子云平台客户端](../1_cqlib/7_tianyan/0_overview.md)：如果需要把线路提交到云端后端执行，可继续学习 QCIS 导出、后端选择、任务提交和结果获取流程。