# QuantumBlocks量子积木

**Repository Path**: zaohuasage/quantum-blocks

## Basic Information

- **Project Name**: QuantumBlocks量子积木
- **Description**: 致力于量子技术平民化，让研究量子像小学生搭积木一样简单（附带基础量子工具 / 贝尔态制备工具等）
- **Primary Language**: Python
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: https://orcid.org/0009-0009-2218-019X
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-09-01
- **Last Updated**: 2025-09-21

## Categories & Tags

**Categories**: Uncategorized

**Tags**: 前沿技术

## README

# QuantumBlocks 量子积木

## 🌟 项目介绍
主打「一台电脑完成量子模拟」，致力于让量子技术像“搭积木”一样平民化～附带基础量子工具、贝尔态制备工具等，帮科研爱好者、学生轻松入门量子实验。


## 🧩 软件架构
基于 Python 生态做了**模块化分层设计**：
- 底层：调用 Qiskit、Qutip 等成熟库（量子比特模拟、量子门运算这些核心能力，被统一接口封装，不用关心底层差异）；
- 中层：两大功能模块——
  - 「基础量子工具」：标准化搭量子电路、测量、结果分析；
  - 「贝尔态专项」：一键制备贝尔态、保真度验证、抗噪优化；
- 顶层：极简 API（一行代码调用核心功能）+ 可选图形界面，零基础也能快速上手～

模块设计是「低耦合 + 高内聚」：底层能灵活换后端（Qiskit/Qutip 想换就换），中层模块独立（新增工具直接加模块），顶层适配科研、教学等场景，扩展维护都方便～


## 🚀 已开源项目：
### 1.贝尔态单态制备 Preparation of Bell state singlet（子文件夹同名） 
- **目标**：编程实现贝尔态（|Φ⁺⟩）的制备与测量，验证量子纠缠的概率特性（对比 1024 次/100 万次射击的实验结果）。
- **理论基础**：贝尔态 |Φ⁺⟩ = (|00⟩ + |11⟩) / √2，测量时会以 ~50% 概率得到 |00⟩ 或 |11⟩，从不会出现 |01⟩/|10⟩。
- **结论**：
  1. 纠缠验证：所有实验都没出现 |01⟩/|10⟩，完美符合理论；
  2. 大数定律：射击次数越多，结果越接近 50%（100 万次偏差 < 0.1%，1024 次最高偏差 4.49%）；
  3. 可复现性：多次实验结果稳定，能当量子纠缠教学/研究的基础案例～

复现完您将得到电路图和参数：
```bash
贝尔态|Φ⁺⟩电路：
     ┌───┐     ┌─┐
q_0: ┤ H ├──■──┤M├───
     └───┘┌─┴─┐└╥┘┌─┐
q_1: ─────┤ X ├─╫─┤M├
          └───┘ ║ └╥┘
c: 2/═══════════╩══╩═
                0  1
测量结果： {'11': 499720, '00': 500280}
```

## 🛠️ 安装教程（适配 Python 3.12.4）

### 1. 确认 Python 版本
终端输入 `python --version` 验证版本，必须是 3.12.4～版本不对的话，去 [Python 官网](https://www.python.org/downloads/release/python-3124/) 下载安装。


### 2. 超简单虚拟环境搭建（小白直接抄）
不用懂原理，跟着“复制-粘贴-改路径”就行，5 步搞定：

#### 步骤 1：建个英文文件夹
在电脑里选个盘（比如 F 盘），新建文件夹（名字用英文，比如 `QuantumLab`，别带空格）。
例：`F:\QuantumLab`

#### 步骤 2：开终端
按 `Win+R` → 输入 `cmd` → 回车，打开黑窗口（终端）。

#### 步骤 3：1 行命令建虚拟环境
把下面命令里的 `F:\QuantumLab` 换成你自己的路径，粘贴到终端回车：
```bash
python -m venv F:\QuantumLab\newenv
```

#### 步骤 4：1 行命令激活环境
继续把 `F:\QuantumLab` 换成你自己的路径，粘贴命令回车：
```bash
F:\QuantumLab\newenv\Scripts\activate.bat
```
✅ 激活成功：终端开头会显示 `(newenv)`。

#### 步骤 5：进入项目文件夹
把 `QuantumBlocks` 项目放到 `F:\QuantumLab` 里，终端输入：
```bash
cd F:\QuantumLab\QuantumBlocks
```

### 3. 安装全套依赖库
终端里复制下面的命令（加清华源能加速，`--no-cache-dir` 避免缓存冲突），回车执行：
```bash
pip install qiskit==2.1.1 qiskit-aer==0.17.1 qutip==4.7.5 numpy==2.3.1 pandas==2.3.1 matplotlib==3.10.3 scipy==1.16.0 seaborn==0.13.2 tqdm==4.67.1 pyserial==3.5 networkx==3.5 pylatexenc==2.10 sympy==1.14.0 scikit-learn==1.7.1 cryptography==45.0.6 openpyxl==3.1.5 pymatgen==2025.6.14 ase==3.26.0 --no-cache-dir -i https://pypi.tuna.tsinghua.edu.cn/simple
```
#### 依赖库作用说明（小白版）：

##### 🔹 核心量子库（量子计算的“发动机”）
- `qiskit`：IBM 出的量子编程库，能搭量子电路、模拟量子态（比如贝尔态就靠它）；
- `qiskit-aer`：Qiskit 的“加速器”，让量子模拟跑得更快；
- `qutip`：专门处理量子力学计算的库，适合更深入的量子态分析。


##### 🔹 数据处理库（量子实验的“计算器”）
- `numpy`：Python 数学计算的“地基”，处理数组、矩阵这些量子计算里的基础数据；
- `pandas`：把量子实验结果做成表格，方便看数据、算概率；
- `scipy`：高级数学工具，解决量子力学里的复杂方程。


##### 🔹 画图/展示库（实验结果的“化妆师”）
- `matplotlib`：画量子实验结果图（比如概率分布直方图）；
- `seaborn`：给图表“化妆”，让结果图更好看、更易读；
- `pylatexenc`：把量子公式（比如 |Φ⁺⟩）正确显示在图上或文档里。


##### 🔹 工具类库（辅助功能的“小助手”）
- `tqdm`：显示安装/运行进度条，知道“卡在哪了”；
- `networkx`：处理量子电路里的“节点和连接”，比如量子门之间的关系；
- `sympy`：符号计算工具，帮着推导量子力学公式；
- `scikit-learn`：分析大量量子实验数据时，用它做统计和预测；
- `cryptography`：涉及量子加密相关功能时用（可选功能）；
- `openpyxl`：读写 Excel 表格，方便导出实验结果；
- `pymatgen + ase`：处理量子与材料科学结合的场景（扩展功能，比如模拟量子在材料中的行为）；
- `pyserial`：连接硬件设备（比如真实量子芯片）时，用它传数据（扩展功能）。

### 4. 从 Gitee 下载代码并运行
#### 步骤 1：下载代码压缩包
1. 打开 Gitee 仓库（比如 `https://gitee.com/zaohuasage/QuantumBlocks`）；
2. 点右上角「克隆/下载」→ 选「下载 ZIP」；
3. 把压缩包存到 `F:\QuantumLab\QuantumBlocks` 里，右键解压到当前文件夹（确保 `.py` 脚本直接在 `QuantumBlocks` 里，别嵌套子文件夹）。

#### 步骤 2：运行代码
1. 确保终端有 `(newenv)`，且通过 `cd` 进入了代码文件夹；
2. 终端输入 `python 脚本名.py`（比如 `python bell_state.py`）；
3. ✅ 成功标志：终端打印计算过程，最后弹出结果图表（如贝尔态概率分布）。


## 📖 使用说明
1. 环境准备：确保已按「安装教程」完成 Python 3.12.4 配置、虚拟环境激活（终端显示 `(newenv)`）及全套依赖安装；
2. 代码获取：通过 Gitee 仓库「下载 ZIP 压缩包」或「Git 克隆」获取代码，将 `.py` 脚本放入项目文件夹根目录（避免嵌套）；
3. 运行脚本：在激活的虚拟环境终端中，进入代码文件夹，输入 `python 脚本文件名.py`，终端显示计算过程且弹出结果图表即成功；
4. 功能扩展：如需测试其他量子态功能，可在项目文件夹中新增 `.py` 脚本，调用 Qiskit、Qutip 等库编写代码，按步骤 3 运行即可。

## 📜 许可证
本项目采用 [Apache License 2.0](https://www.apache.org/licenses/LICENSE-2.0) 开源许可证。