quonic 0.2.0__tar.gz

quonic-0.2.0/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

quonic-0.2.0/PKG-INFO

@@ -0,0 +1,254 @@
+Metadata-Version: 2.4
+Name: quonic
+Version: 0.2.0
+Summary: 量子编程，像写 Python 一样简单
+Author-email: ChrisLee <Christina_Llap_Yuen@outlook.com>
+License-Expression: Apache-2.0
+Keywords: quantum,quantum-computing,qiskit,cirq,pennylane
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: Physics
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: qiskit
+Requires-Dist: qiskit>=1.0; extra == "qiskit"
+Requires-Dist: qiskit-aer>=0.14; extra == "qiskit"
+Provides-Extra: cirq
+Requires-Dist: cirq>=1.0; extra == "cirq"
+Provides-Extra: pennylane
+Requires-Dist: pennylane>=0.36; extra == "pennylane"
+Provides-Extra: quantum-inspire
+Requires-Dist: qiskit-quantuminspire>=0.18; extra == "quantum-inspire"
+Requires-Dist: quantuminspire>=4.0; extra == "quantum-inspire"
+Requires-Dist: qiskit<2.4.0; extra == "quantum-inspire"
+Provides-Extra: algorithms
+Requires-Dist: numpy>=1.24; extra == "algorithms"
+Requires-Dist: scipy>=1.10; extra == "algorithms"
+Provides-Extra: viz
+Requires-Dist: matplotlib>=3.5; extra == "viz"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: numpy>=1.24; extra == "dev"
+Requires-Dist: scipy>=1.10; extra == "dev"
+Requires-Dist: matplotlib>=3.5; extra == "dev"
+Requires-Dist: ruff>=0.9; extra == "dev"
+Dynamic: license-file
+
+# QuoNic — 量子编程，像写 Python 一样简单
+
+[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](LICENSE)
+[![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/)
+[![Qiskit](https://img.shields.io/badge/Qiskit-1.0+-green.svg)](https://qiskit.org/)
+[![Cirq](https://img.shields.io/badge/Cirq-1.0+-orange.svg)](https://quantumai.google/cirq)
+
+**QuoNic 是一个让量子编程变得像写 Python 一样简单的工具。**
+
+不需要学 `QuantumCircuit`，不需要理解 `backend`，不需要手动 `measure`。你会写 Python，就会用量子计算。
+
+---
+
+## 🚀 30 秒快速开始
+
+```python
+from quonic import qgate, qshow
+from quonic.gates import H, CX
+
+qgate(H, 0)
+qgate(CX, 0, 1)
+qshow()
+```
+
+**这是量子计算中最经典的贝尔态（Bell State）。** 同样的功能，用 Qiskit 原生代码需要 10+ 行。QuoNic 只需要 3 行。运行结果会直接显示在终端或 Jupyter 中。
+
+更多**复制即跑**的示例（GHZ、`qif`、`QInt`、Grover、VQE、QAOA、噪声）见 [`examples/`](examples/)。
+
+---
+
+## 📦 安装
+
+```bash
+pip install quonic
+```
+
+后端是可选依赖，按需安装。要一键装齐三个后端（含算法模板的 numpy/scipy）：
+
+```bash
+pip install 'quonic[qiskit,cirq,pennylane,algorithms]'
+```
+
+只装某一个后端，例如只用 Cirq：`pip install 'quonic[cirq]'`。未安装的后端在调用时会给出明确的中文提示。
+
+可视化是独立可选依赖：`pip install 'quonic[viz]'`（仅 matplotlib，不引入 Graphviz / Seaborn / NetworkX）。
+
+---
+
+## ✨ 核心特性
+
+### 1. 极简语法：3 行代码跑通贝尔态
+
+你不需要理解“量子电路对象”，不需要选择“后端模拟器”，不需要手动“测量”。QuoNic 替你处理一切。
+
+### 2. 一个参数切换所有后端
+
+```python
+# 使用 Qiskit 模拟器（默认）
+qshow(backend='qiskit')
+
+# 切换到 Cirq
+qshow(backend='cirq')
+
+# 切换到 PennyLane
+qshow(backend='pennylane')
+
+# 真实硬件（IBM / AWS / Google 云端）规划中，暂未开放
+qshow(backend='ibm_brisbane')  # TODO: 尚未支持
+```
+
+**同一段代码，不加修改，跑在任何后端上。** 极简语法 + 后端无关，是 QuoNic 的组合差异化。
+
+### 3. 条件门与”if = 叠加态”
+
+QuoNic 用 `qif` 实现量子叠加控制，并严格区分两种概念：
+
+- **量子叠加控制（`qif`，已实现）**：控制比特处于叠加态时**不测量**，两个分支
+  相干叠加，产生真纠缠——这是”两种分支同时发生”，不是先测量再二选一。
+  ```python
+  from quonic import qgate, qif, qshow
+  from quonic.gates import H, X, I
+
+  qgate(H, 0)                       # 控制比特进入叠加态
+  qif(0).then(X, 1).else_(I, 1)     # q0==1 翻转 q1，否则不动（= 受控 X）
+  qshow()
+  ```
+  `else_(I, ...)` 里的 `I` 是恒等门，让「受控门 = qif 特例」写得自然。
+- **条件门（经典控制，规划中）**：先测量、再按结果选择分支，这是”坍缩之后的经典分支”。
+  ```python
+  # 规划中：基于测量结果的条件门
+  # qgate(H, 0)
+  # if qgate(MEASURE, 0) == 0:
+  #     qgate(X, 1)
+  # else:
+  #     qgate(Z, 1)
+  ```
+
+我们不把”测量后的经典分支”包装成”叠加态”——教错物理，比不教更糟。
+
+### 4. 真正的“技术惠普”
+
+- **中文错误信息**：报错时告诉你“哪里错了、为什么错、怎么改”
+- **自动补全**：在 VS Code / Jupyter 中自动提示门名称和参数
+- **自动测量**：忘记写 `measure`？`qshow()` 自动补全
+
+### 5. 智能调度器：自动挑最快的方法
+
+量子模拟有四种方法，快慢差几个数量级，选错直接撞墙：
+
+| 方法 | 复杂度 | 适合 |
+|------|--------|------|
+| `statevector` | 2^n | 通用默认 |
+| `stabilizer` | 多项式 | 纯 Clifford 电路（如纠错码） |
+| `matrix_product_state` | 随树宽增长 | 低树宽电路（如 QAOA） |
+| `density_matrix` | 4^n | 噪声模拟 |
+
+QuoNic 的调度器根据电路特征（门类型、树宽、是否含噪声）自动选择，不用你手动
+指定方法。实测证据：**GHZ(24) 快 36 倍、QAOA(24) 快 19 倍**，Grover 的
+`mcz` 只有 `statevector` 能跑，调度器会自动绕开会崩溃的方法。
+
+```python
+from quonic.scheduler import schedule
+rec = schedule(circuit)   # -> Recommendation(backend='qiskit', method='stabilizer')
+```
+
+详见 [调度器基准与实测数据](docs/benchmarks.md)。
+
+### 6. 全量可视化套件：23 类图，只用 Matplotlib
+
+```python
+from quonic.viz import plot_circuit, plot_counts, plot_decision_tree
+
+plot_circuit(circuit)        # 门序列电路图
+plot_counts(result)          # 测量直方图
+plot_decision_tree()         # 调度决策树
+```
+
+23 类图覆盖四层：**用户刚需**（电路图 / 直方图 / 拓扑图）、**调度器证据**
+（方法对比 / 决策树 / 热力图 / 降级链 / 特征雷达图）、**算法教学**（能量收敛
+/ Grover 振幅 / 态向量 / 布洛赫球）、**量子态**（密度矩阵 / 纠缠 / 门矩阵 /
+路由 / 逐门态演化 / 噪声成本）。全部只用 matplotlib 一个依赖，懒加载，
+`import quonic` 零开销。详见 [可视化套件](docs/visualization.md)。
+
+---
+
+## 📊 对比：QuoNic vs Qiskit
+
+| 场景 | Qiskit | QuoNic |
+|------|--------|-------|
+| **跑通第一个量子程序** | 需要理解 5-8 个新概念 | 只需要 2 个概念：`qgate` 和 `qshow` |
+| **代码行数（贝尔态）** | 8-12 行 | **3 行** |
+| **从安装到看到结果** | 30-60 分钟 | **2-3 分钟** |
+| **切换后端** | 重写全部代码 | **改一个参数** |
+
+---
+
+## 🧠 为什么叫 QuoNic？
+
+- **Qu** — Quantum（量子）
+- **onic** — 词尾（photonic / electronic），意为“属于量子的、关于量子的”
+- 读作 /ˈkwɑnɪk/（“阔尼克”），一句话：**“量子计算的”**（the quantum one）
+
+---
+
+## 🛠️ 当前支持的后端
+
+| 后端 | 状态 | 说明 |
+|------|------|------|
+| Qiskit | ✅ 稳定 | IBM 生态 · 本地模拟器 |
+| Cirq | ✅ 稳定 | Google 生态 · 本地模拟器 |
+| PennyLane | ✅ 稳定 | 量子机器学习 · 本地模拟器 |
+| 真实硬件 | 📅 规划中 | IBM / AWS / Google 云端量子硬件 |
+| 更多后端 | 📅 规划中 | Amazon Braket, PyQuil... |
+
+> **注意**：目前三个后端都运行在**本地模拟器**上，尚未接入真实量子硬件。接入云端硬件（IBM / AWS Braket / Google）是后续优先级，见 [路线图](#)。
+
+为硬件铺路，QuoNic 已内置 `CouplingMap`（耦合图）、`compile()` 编译 seam，以及 `decompose()` 门分解——把高阶门（`cp` / `ccx` / `mcz`）展开成基础门集。后者是 QuoNic 自己拥有的「可移植核心」：用户不被某个后端的电路形状绑住，Grover 的 `mcz` 分解成 `cx / h / p` 后能跑通所有后端方法。已内置 `route_swaps()` 贪心 SWAP 路由（配合 `plot_routing` 可视化），将来接 IBM / 国产引擎时，只需在编译层接入，无需改动 IR 或调度器。
+
+---
+
+## 📖 文档与教程
+
+- [快速入门](docs/quickstart.md) — 5 分钟上手 QuoNic
+- [Jupyter 教程](docs/tutorial.ipynb) — 可运行的交互单元
+- [门列表](docs/gates.md) — 所有内置门及其用法
+- [自定义门](docs/custom_gates.md) — 注册你自己的门
+- [后端切换](docs/backends.md) — 一个参数切换所有引擎
+- [调度器基准与实测数据](docs/benchmarks.md) — 自动选最快方法的护城河
+- [可视化套件](docs/visualization.md) — 23 类图，只用 Matplotlib
+- [国产硬件调研](docs/domestic-hardware.md) — QPanda3 / CqLib 接入评估
+
+---
+
+## 🤝 贡献指南
+
+QuoNic 是一个开源项目（Apache 2.0），欢迎任何形式的贡献：
+
+- 报告 Bug
+- 提出新功能建议
+- 提交代码（新后端适配器、新门、新功能）
+- 完善文档和教程
+
+请阅读 [CONTRIBUTING.md](CONTRIBUTING.md) 了解详细信息。
+
+---
+
+## 📄 许可证
+
+QuoNic 使用 [Apache License 2.0](LICENSE)，对商用和闭源友好，同时提供专利保护。
+
+---
+
+## 🌟 给项目加星
+
+如果 QuoNic 对你有帮助，请在 GitHub 上给我们一个 ⭐️。你的支持是我们持续改进的动力。

quonic-0.2.0/README.md

@@ -0,0 +1,215 @@
+# QuoNic — 量子编程，像写 Python 一样简单
+
+[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](LICENSE)
+[![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/)
+[![Qiskit](https://img.shields.io/badge/Qiskit-1.0+-green.svg)](https://qiskit.org/)
+[![Cirq](https://img.shields.io/badge/Cirq-1.0+-orange.svg)](https://quantumai.google/cirq)
+
+**QuoNic 是一个让量子编程变得像写 Python 一样简单的工具。**
+
+不需要学 `QuantumCircuit`，不需要理解 `backend`，不需要手动 `measure`。你会写 Python，就会用量子计算。
+
+---
+
+## 🚀 30 秒快速开始
+
+```python
+from quonic import qgate, qshow
+from quonic.gates import H, CX
+
+qgate(H, 0)
+qgate(CX, 0, 1)
+qshow()
+```
+
+**这是量子计算中最经典的贝尔态（Bell State）。** 同样的功能，用 Qiskit 原生代码需要 10+ 行。QuoNic 只需要 3 行。运行结果会直接显示在终端或 Jupyter 中。
+
+更多**复制即跑**的示例（GHZ、`qif`、`QInt`、Grover、VQE、QAOA、噪声）见 [`examples/`](examples/)。
+
+---
+
+## 📦 安装
+
+```bash
+pip install quonic
+```
+
+后端是可选依赖，按需安装。要一键装齐三个后端（含算法模板的 numpy/scipy）：
+
+```bash
+pip install 'quonic[qiskit,cirq,pennylane,algorithms]'
+```
+
+只装某一个后端，例如只用 Cirq：`pip install 'quonic[cirq]'`。未安装的后端在调用时会给出明确的中文提示。
+
+可视化是独立可选依赖：`pip install 'quonic[viz]'`（仅 matplotlib，不引入 Graphviz / Seaborn / NetworkX）。
+
+---
+
+## ✨ 核心特性
+
+### 1. 极简语法：3 行代码跑通贝尔态
+
+你不需要理解“量子电路对象”，不需要选择“后端模拟器”，不需要手动“测量”。QuoNic 替你处理一切。
+
+### 2. 一个参数切换所有后端
+
+```python
+# 使用 Qiskit 模拟器（默认）
+qshow(backend='qiskit')
+
+# 切换到 Cirq
+qshow(backend='cirq')
+
+# 切换到 PennyLane
+qshow(backend='pennylane')
+
+# 真实硬件（IBM / AWS / Google 云端）规划中，暂未开放
+qshow(backend='ibm_brisbane')  # TODO: 尚未支持
+```
+
+**同一段代码，不加修改，跑在任何后端上。** 极简语法 + 后端无关，是 QuoNic 的组合差异化。
+
+### 3. 条件门与”if = 叠加态”
+
+QuoNic 用 `qif` 实现量子叠加控制，并严格区分两种概念：
+
+- **量子叠加控制（`qif`，已实现）**：控制比特处于叠加态时**不测量**，两个分支
+  相干叠加，产生真纠缠——这是”两种分支同时发生”，不是先测量再二选一。
+  ```python
+  from quonic import qgate, qif, qshow
+  from quonic.gates import H, X, I
+
+  qgate(H, 0)                       # 控制比特进入叠加态
+  qif(0).then(X, 1).else_(I, 1)     # q0==1 翻转 q1，否则不动（= 受控 X）
+  qshow()
+  ```
+  `else_(I, ...)` 里的 `I` 是恒等门，让「受控门 = qif 特例」写得自然。
+- **条件门（经典控制，规划中）**：先测量、再按结果选择分支，这是”坍缩之后的经典分支”。
+  ```python
+  # 规划中：基于测量结果的条件门
+  # qgate(H, 0)
+  # if qgate(MEASURE, 0) == 0:
+  #     qgate(X, 1)
+  # else:
+  #     qgate(Z, 1)
+  ```
+
+我们不把”测量后的经典分支”包装成”叠加态”——教错物理，比不教更糟。
+
+### 4. 真正的“技术惠普”
+
+- **中文错误信息**：报错时告诉你“哪里错了、为什么错、怎么改”
+- **自动补全**：在 VS Code / Jupyter 中自动提示门名称和参数
+- **自动测量**：忘记写 `measure`？`qshow()` 自动补全
+
+### 5. 智能调度器：自动挑最快的方法
+
+量子模拟有四种方法，快慢差几个数量级，选错直接撞墙：
+
+| 方法 | 复杂度 | 适合 |
+|------|--------|------|
+| `statevector` | 2^n | 通用默认 |
+| `stabilizer` | 多项式 | 纯 Clifford 电路（如纠错码） |
+| `matrix_product_state` | 随树宽增长 | 低树宽电路（如 QAOA） |
+| `density_matrix` | 4^n | 噪声模拟 |
+
+QuoNic 的调度器根据电路特征（门类型、树宽、是否含噪声）自动选择，不用你手动
+指定方法。实测证据：**GHZ(24) 快 36 倍、QAOA(24) 快 19 倍**，Grover 的
+`mcz` 只有 `statevector` 能跑，调度器会自动绕开会崩溃的方法。
+
+```python
+from quonic.scheduler import schedule
+rec = schedule(circuit)   # -> Recommendation(backend='qiskit', method='stabilizer')
+```
+
+详见 [调度器基准与实测数据](docs/benchmarks.md)。
+
+### 6. 全量可视化套件：23 类图，只用 Matplotlib
+
+```python
+from quonic.viz import plot_circuit, plot_counts, plot_decision_tree
+
+plot_circuit(circuit)        # 门序列电路图
+plot_counts(result)          # 测量直方图
+plot_decision_tree()         # 调度决策树
+```
+
+23 类图覆盖四层：**用户刚需**（电路图 / 直方图 / 拓扑图）、**调度器证据**
+（方法对比 / 决策树 / 热力图 / 降级链 / 特征雷达图）、**算法教学**（能量收敛
+/ Grover 振幅 / 态向量 / 布洛赫球）、**量子态**（密度矩阵 / 纠缠 / 门矩阵 /
+路由 / 逐门态演化 / 噪声成本）。全部只用 matplotlib 一个依赖，懒加载，
+`import quonic` 零开销。详见 [可视化套件](docs/visualization.md)。
+
+---
+
+## 📊 对比：QuoNic vs Qiskit
+
+| 场景 | Qiskit | QuoNic |
+|------|--------|-------|
+| **跑通第一个量子程序** | 需要理解 5-8 个新概念 | 只需要 2 个概念：`qgate` 和 `qshow` |
+| **代码行数（贝尔态）** | 8-12 行 | **3 行** |
+| **从安装到看到结果** | 30-60 分钟 | **2-3 分钟** |
+| **切换后端** | 重写全部代码 | **改一个参数** |
+
+---
+
+## 🧠 为什么叫 QuoNic？
+
+- **Qu** — Quantum（量子）
+- **onic** — 词尾（photonic / electronic），意为“属于量子的、关于量子的”
+- 读作 /ˈkwɑnɪk/（“阔尼克”），一句话：**“量子计算的”**（the quantum one）
+
+---
+
+## 🛠️ 当前支持的后端
+
+| 后端 | 状态 | 说明 |
+|------|------|------|
+| Qiskit | ✅ 稳定 | IBM 生态 · 本地模拟器 |
+| Cirq | ✅ 稳定 | Google 生态 · 本地模拟器 |
+| PennyLane | ✅ 稳定 | 量子机器学习 · 本地模拟器 |
+| 真实硬件 | 📅 规划中 | IBM / AWS / Google 云端量子硬件 |
+| 更多后端 | 📅 规划中 | Amazon Braket, PyQuil... |
+
+> **注意**：目前三个后端都运行在**本地模拟器**上，尚未接入真实量子硬件。接入云端硬件（IBM / AWS Braket / Google）是后续优先级，见 [路线图](#)。
+
+为硬件铺路，QuoNic 已内置 `CouplingMap`（耦合图）、`compile()` 编译 seam，以及 `decompose()` 门分解——把高阶门（`cp` / `ccx` / `mcz`）展开成基础门集。后者是 QuoNic 自己拥有的「可移植核心」：用户不被某个后端的电路形状绑住，Grover 的 `mcz` 分解成 `cx / h / p` 后能跑通所有后端方法。已内置 `route_swaps()` 贪心 SWAP 路由（配合 `plot_routing` 可视化），将来接 IBM / 国产引擎时，只需在编译层接入，无需改动 IR 或调度器。
+
+---
+
+## 📖 文档与教程
+
+- [快速入门](docs/quickstart.md) — 5 分钟上手 QuoNic
+- [Jupyter 教程](docs/tutorial.ipynb) — 可运行的交互单元
+- [门列表](docs/gates.md) — 所有内置门及其用法
+- [自定义门](docs/custom_gates.md) — 注册你自己的门
+- [后端切换](docs/backends.md) — 一个参数切换所有引擎
+- [调度器基准与实测数据](docs/benchmarks.md) — 自动选最快方法的护城河
+- [可视化套件](docs/visualization.md) — 23 类图，只用 Matplotlib
+- [国产硬件调研](docs/domestic-hardware.md) — QPanda3 / CqLib 接入评估
+
+---
+
+## 🤝 贡献指南
+
+QuoNic 是一个开源项目（Apache 2.0），欢迎任何形式的贡献：
+
+- 报告 Bug
+- 提出新功能建议
+- 提交代码（新后端适配器、新门、新功能）
+- 完善文档和教程
+
+请阅读 [CONTRIBUTING.md](CONTRIBUTING.md) 了解详细信息。
+
+---
+
+## 📄 许可证
+
+QuoNic 使用 [Apache License 2.0](LICENSE)，对商用和闭源友好，同时提供专利保护。
+
+---
+
+## 🌟 给项目加星
+
+如果 QuoNic 对你有帮助，请在 GitHub 上给我们一个 ⭐️。你的支持是我们持续改进的动力。