Metadata-Version: 2.5
Name: gpuqviz
Version: 0.5.0
Summary: GPU-accelerated quantum state evolution visualization and video rendering
Author: gpuqviz contributors
License: Apache-2.0
License-File: LICENSE
Requires-Python: >=3.9
Requires-Dist: av>=15.1
Requires-Dist: moderngl>=5.10
Requires-Dist: numpy>=1.24
Requires-Dist: pillow>=10.0
Requires-Dist: pydantic>=2.6
Requires-Dist: typer>=0.12
Provides-Extra: cpu-fallback
Requires-Dist: numba>=0.59; extra == 'cpu-fallback'
Provides-Extra: dev
Requires-Dist: mypy; extra == 'dev'
Requires-Dist: pytest-cov; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff; extra == 'dev'
Provides-Extra: gpu
Requires-Dist: cupy-cuda12x>=13.0; extra == 'gpu'
Requires-Dist: pynvvideocodec>=2.0; (python_version >= '3.10') and extra == 'gpu'
Provides-Extra: preview
Requires-Dist: moderngl-window>=2.4; extra == 'preview'
Provides-Extra: pyqpanda
Requires-Dist: pyqpanda>=3.8; extra == 'pyqpanda'
Provides-Extra: qiskit
Requires-Dist: qiskit-aer>=0.14; extra == 'qiskit'
Requires-Dist: qiskit>=1.0; extra == 'qiskit'
Provides-Extra: qiskit-gpu
Requires-Dist: qiskit-aer-gpu>=0.14; extra == 'qiskit-gpu'
Requires-Dist: qiskit>=1.0; extra == 'qiskit-gpu'
Description-Content-Type: text/markdown

<div align="center">

# ⚛️ gpuqviz

**GPU 加速的量子态演化可视化与视频渲染库**

把 qiskit 电路一键渲染成布洛赫球与概率热图动画 —— matplotlib 方案 30 分钟的活，这里 20 秒干完。

[![PyPI](https://img.shields.io/badge/pypi-0.1.0-blue)](https://pypi.org/project/gpuqviz/)
[![Python](https://img.shields.io/badge/python-3.9%2B-blue)](https://www.python.org/)
[![License](https://img.shields.io/badge/license-Apache--2.0-green)](https://github.com/Poplavis/gpuqviz/blob/main/LICENSE)
[![CI](https://img.shields.io/badge/CI-GitHub_Actions-informational)](https://github.com/Poplavis/gpuqviz/actions/workflows/ci.yml)

</div>

---

## 为什么需要它

用 matplotlib 逐帧渲染 15 秒的量子态演化视频，通常要等 **30+ 分钟**：CPU 光栅化、逐帧写 PNG、ffmpeg 软编码，三头慢。

gpuqviz 把整条流水线搬到 GPU 上：**离屏 GLSL 渲染 → 显存直取 → 进程内编码 → MP4**，全程零中间文件；只仿真约 120 个关键帧，输出帧率由球面插值在 GPU 上补齐。15 秒 1080p60 视频，**20 秒出片**。

| | 传统方案 | gpuqviz |
|---|---|---|
| 渲染 | matplotlib 逐帧 CPU 光栅化 | GLSL 着色器离屏渲染 |
| 中间产物 | 每帧一张 PNG | 无（帧直接进编码器） |
| 编码 | ffmpeg 子进程软编码 | NVENC 硬编码 → PyAV 回退 |
| 帧率 | 仿真多少帧就多少帧 | 关键帧 + slerp 插值，任意帧率 |

## 演示

**布洛赫球 + 概率热图分屏**（相机环绕动画，SDF 中文标题）：

![showcase](docs/images/showcase_bloch_heatmap.png)

**GHZ 态三 qubit 演化**：

![ghz](docs/images/ghz_split_view.png)

> 视频样例见 `examples/` 目录脚本一键生成：`python examples/showcase.py`

## 特性

- ⚡ **快**：GPU 光栅化 + 关键帧插值，15s@60fps 视频秒级~分钟级出片
- 📦 **零中间文件**：FBO 帧直通进程内编码器，不落盘
- 🎥 **NVENC 硬编码**（可选）：cupy RGBA → GPU NV12 kernel → NVENC，全程不下显存；不可用时自动回退 `libx264`
- 🎨 **多种渲染器**：布洛赫球（Phong 球壳/轨迹尾/多 qubit）、概率/相位热图（viridis/inferno）、相位色盘
- 📝 **SDF 中文标注**：freetype 烘焙图集，任意字号锐利，运行时零 freetype 依赖
- 🎬 **Scene 声明式 API**：JSON 场景文件 + CLI 一条命令出片，相机轨道动画
- 🧊 **CPU 回退后端**：无 OpenGL 环境自动降级 numpy 软光栅（limited 样式）
- 🔬 **qiskit 原生衔接**：直接吃 `QuantumCircuit` / `Statevector`，qiskit 仅为可选依赖
- 🐼 **pyqpanda 兼容**：本源量子 `QProg` 经 ORIGINIR 转换 + 内置 numpy 态矢量模拟器接入，`pip install gpuqviz[pyqpanda]`
- 🖱️ **交互式 3D 播放器**：导出单文件 HTML（约 0.7MB，离线可开）——播放/暂停、0.25×~4× 倍速、时间轴拖动、鼠标旋转缩放视角，下方实时显示各基态概率/振幅/相位与 Bloch 向量

## 安装

```bash
pip install gpuqviz[qiskit]     # 推荐：qiskit 输入支持
pip install gpuqviz[gpu]        # 追加 CUDA 12.x（cupy + NVENC，需 Python ≥3.10）
pip install gpuqviz[preview]    # 追加实时预览
```

<details>
<summary>环境要求</summary>

- Python ≥ 3.9（NVENC 硬编码路径需 ≥ 3.10）
- 任何支持 OpenGL 3.3 的 GPU（**无 N 卡也能跑**，编码自动回退软编码）
- 可选：NVIDIA GPU + CUDA 12.x（cupy 加速 + NVENC）

</details>

## 快速上手

### 一行出片

```python
from qiskit import QuantumCircuit
from gpuqviz import render_bloch_video

qc = QuantumCircuit(2)
qc.h(0)
qc.cx(0, 1)

render_bloch_video(circuit=qc, out="out/bell.mp4")   # 1080p60 布洛赫球动画
```

### 概率热图

```python
from gpuqviz import render_heatmap_video

render_heatmap_video(circuit=qc, basis="probability", out="out/hm.mp4")
```

### Scene 声明式 API

```python
from gpuqviz import render
from gpuqviz.scene import Scene, BlochTrack, HeatmapTrack, Camera

scene = Scene(
    duration=5.0, fps=60,
    title="贝尔态演化",
    camera=Camera(azimuth=(0.0, 60.0), elevation=(25.0, 35.0)),  # 相机轨道动画
    tracks=[
        BlochTrack(states_path="states.npz", trail=True, layout="top"),
        HeatmapTrack(states_path="states.npz", basis="probability", layout="bottom"),
    ],
)
render(scene, out="out/scene.mp4")
```

态矢量数据准备：`np.savez("states.npz", states=key_states)`，形状 `(K, 2**n)` complex，
K 为关键帧数。场景可持久化为 JSON：[examples/scene.json](examples/scene.json)。

### 交互式 3D 播放器（单文件 HTML）

```python
from gpuqviz import export_html

export_html(circuit=qc, out="out/viewer.html", title="贝尔态演化")
```

双击 `viewer.html` 即可打开：3D 视口（鼠标拖拽旋转 / 滚轮缩放）、播放/暂停（空格）、
0.25×~4× 倍速、时间轴拖动（←/→ 逐帧步进），底部实时显示当前量子状态——
每个基态的概率条、振幅与相位，以及各 qubit 的 Bloch 向量。

输入为 `circuit` 时，播放器顶部自动绘制 **SVG 量子电路图**，与 Bloch 球双向联动：
播放时当前正在执行的门以橙色高亮；点击电路图中的任意门可跳转到该门对应的播放时刻，
Bloch 球与状态面板同步更新。支持的门符号：单量子门方框、受控门（控制点 + ⊕ 目标）、
SWAP（× 符号）、ISWAP（跨行方框）、参数门（`RX(π/2)` 等标签）。

### Jupyter 交互集成

```python
from qiskit import QuantumCircuit
import gpuqviz

qc = QuantumCircuit(2)
qc.h(0); qc.cx(0, 1)

# notebook 中一行代码 → 内嵌可交互 3D 播放器（断网可用）
gpuqviz.show(qc)
```

`show()` 自动检测运行环境：

- **Jupyter notebook / JupyterLab**：通过 `IPython.display.HTML` 以 iframe `srcdoc`
  内嵌自包含 HTML（three.js 内联，无需联网），直接出现播放/暂停/倍速/时间轴的 3D 播放器
- **终端 / 脚本**：回退为写 HTML 文件并打印路径（与 CLI `export` 行为一致）
- **大 payload 降级**：当态矢量数据超 8MB（约 10 qubit × 200 帧）时自动剥离
  状态面板数据（只保留 Bloch 向量），文件从 ~8.7MB 降至 ~0.7MB 并发出警告
- **`as_video=True`**：先渲染 MP4 再用 `IPython.display.Video` 内嵌

```python
# 自定义参数
gpuqviz.show(qc, steps=60, fps=30, height=600, title="贝尔态")

# 渲染视频内嵌
gpuqviz.show(qc, as_video=True, seconds=3, fps=30)
```

### pyqpanda（本源量子）电路

```python
pip install gpuqviz[pyqpanda]

from pyqpanda import CPUQVM, QProg, H, CNOT
from gpuqviz import render_bloch_video

qm = CPUQVM(); qm.init_qvm()
q = qm.qAlloc_many(2)
prog = QProg(); prog << H(q[0]) << CNOT(q[0], q[1])

render_bloch_video(circuit=prog, machine=qm, out="out/bell.mp4")   # 与 qiskit 同一套 API
```

所有入口（`render_bloch_video` / `render_heatmap_video` / `export_html`）均接受
`machine=` 参数直接吃 pyqpanda `QProg`。注意：pyqpanda 的 ORIGINIR 转换必须使用
创建 prog 的同一虚拟机实例，跨实例转换会在原生层崩溃（pyqpanda 已知行为）。

### CLI

```bash
gpuqviz env                           # 环境能力自检（CUDA / OpenGL / NVENC / qiskit）
gpuqviz render scene.json -o out.mp4  # JSON 场景出片
gpuqviz export scene.json -o viewer.html   # 交互式 3D 播放器导出
gpuqviz preview scene.json            # 实时预览（需 [preview] 扩展）
gpuqviz demo --list                   # 列出内置算法
gpuqviz demo --algo grover            # 一行命令演示（默认 HTML 交互播放器）
gpuqviz demo --algo qft --format mp4  # 指定输出格式
gpuqviz demo --algo bell --engine pyqpanda  # 切换模拟引擎
```

### 内置算法库

`gpuqviz.algorithms` 提供 12 个经典量子算法电路构建器，每种算法返回 qiskit `QuantumCircuit`（`engine="qiskit"`）、pyqpanda `QProg`（`engine="pyqpanda"`）或 `list[Gate]`（`engine="numpy"`，无外部依赖），可直接传入可视化 API：

```python
from gpuqviz.algorithms import grover, qft, bell
from gpuqviz import export_html

# 一行构建 + 一行可视化
qc = grover(n=3, marked=0b101, iterations=2)
export_html(circuit=qc, out="out/grover.html", steps=200)

# numpy 路径（不需要 qiskit）
gates = qft(n=3, engine="numpy")
```

| 算法 | 函数 | 类别 | 默认 qubit |
|---|---|---|---|
| Bell 态 | `bell()` | 基础态 | 2 |
| GHZ 态 | `ghz(n=3)` | 基础态 | 3 |
| 均匀叠加 | `superposition(n=3)` | 基础态 | 3 |
| Grover 搜索 | `grover(n=3, marked=0b101)` | 搜索 | 3 |
| 量子傅里叶变换 | `qft(n=3)` | 变换 | 3 |
| 量子相位估计 | `phase_estimation(n_count=3, theta=0.375)` | 估计 | 4 |
| Deutsch-Jozsa | `deutsch_jozsa(oracle_type="balanced", n=3)` | 查询复杂度 | 4 |
| Bernstein-Vazirani | `bernstein_vazirani(secret="101")` | 查询复杂度 | 3 |
| 量子隐形传态 | `teleportation()` | 通信 | 3 |
| 超密编码 | `superdense(message="11")` | 通信 | 2 |
| Simon 算法 | `simon(s="01")` | 查询复杂度 | 4 |
| 量子随机游走 | `quantum_walk(n=3, steps=3)` | 游走 | 3 |

## API 速览

| 函数 | 用途 |
|---|---|
| `render_bloch_video(circuit=…, steps=120, fps=60, trail=…)` | 布洛赫球动画 |
| `render_heatmap_video(states=…, basis=…, colormap=…)` | 概率/相位/幅值热图动画 |
| `render(scene)` | 渲染 Scene 对象 |
| `report_env()` | 环境能力报告 |

完整 API 见 [docs/api.md](docs/api.md)，设计文档见 [DESIGN.md](DESIGN.md)。

## 后端矩阵

| 能力 | gl 后端（默认） | cpu 后端（自动降级） |
|---|---|---|
| 布洛赫球（光照/轨迹/多 qubit） | ✅ 完整 | ✅ 正交投影 limited |
| 概率/相位热图 | ✅ | ❌ |
| SDF 文字 / 相机动画 | ✅ | ❌ |
| 编码链 | NVENC → nvenc(av) → libx264 | libx264 |

自动降级策略：任何一环缺失（无 N 卡、驱动不支持 NVENC、无 OpenGL）都只降速不报错，
`gpuqviz env` 会输出各项能力状态与推荐后端。

## 性能

消费级 NVIDIA GPU（NVENC 不可用，编码回退 libx264）实测，详见 [docs/benchmarks.md](docs/benchmarks.md)：

| 场景 | gl 后端 | cpu 软光栅 |
|---|---|---|
| Bell 态 3s@30fps 720p | **3.9s** | 112.8s |

## 常见问题

<details>
<summary>NVENC 会话打不开（<code>nvEncOpenEncodeSessionEx error 2</code>）</summary>

部分驱动/显卡组合（如 Pascal + R581+ 安全驱动）会失败。库自动回退 PyAV 的
libx264，只影响速度不影响功能，可用 `gpuqviz env` 确认探测结果。
</details>

<details>
<summary>Linux 无显示环境能跑吗</summary>

能。moderngl 走 EGL headless 渲染，无需 X server（需安装 libegl）。
</details>

<details>
<summary>态矢量数据太大了（多 qubit）</summary>

热图与状态显示复杂度随 2^n 增长，建议 n ≤ 10；更大的系统请渲染约化密度矩阵
或局域观测量。
</details>

## 项目结构

```
src/gpuqviz/
├── api.py            # render_bloch_video / render_heatmap_video / render
├── scene.py          # Scene / BlochTrack / HeatmapTrack / Camera (pydantic)
├── evolve.py         # 电路采样 + 批量 einsum Bloch 向量
├── interpolate.py    # slerp / lerp 关键帧插值（含对跖点处理）
├── encode.py         # AvEncoder / NvencEncoder / 探测式回退
├── pipeline.py       # 底层渲染循环
├── render/           # GLContext、布洛赫球、热图、相位盘、SDF 文字、分屏
├── backends/         # 后端探测 + numpy 软光栅
└── assets/           # SDF 字体图集（随 wheel 分发）
```

## 开发

```bash
git clone <repo> && cd gpuqviz
pip install -e .[qiskit,dev]
python -m pytest tests -q          # 测试（23+ 用例）
python examples/showcase.py        # 生成演示视频
python benchmarks/suite.py         # 性能基准
python scripts/gen_font_atlas.py   # 重新烘焙字体图集
```

## Roadmap

- [x] 交互式 3D 播放器：导出单文件 HTML（播放/暂停/倍速/时间轴 + 当前量子状态面板），设计见 [docs/INTERACTIVE_VIEWER.md](docs/INTERACTIVE_VIEWER.md)
- [x] pyqpanda（本源量子）电路兼容
- [x] 高层门/复杂电路兼容：U/U1/U2/U3、受控参数门（CRX/CRY/CRZ/CH/CU）、任意控制位 MCX/MCP/Toffoli、ISWAP，复合门递归展开，`transpile` 兜底未知指令；14 电路对 qiskit 保真度 ≥ 1-1e-9（见 `tests/test_gates_matrix.py`、`examples/grover_mcx.py`）
- [x] 布局/样式系统 + 出版级静态图：`cols`/`figsize` 参数、`bw`（论文黑白）/`poster` 预设、`style_overrides` 覆盖；`render_frame()` 单帧 PNG 导出（scale 超采样抗锯齿，等效 300dpi）
- [x] CPU/无 GL 环境可移植性：numba 加速软光栅（CPU bell 116s→6s，19×）、完整 `HeatmapTrack`/`PhaseDisc`/PIL 文字 CPU 路径、`GPUQVIZ_BACKEND` 环境变量、GL 3.3→3.2 降级链、CI 无 GPU 门禁
- [x] Jupyter 交互集成：`gpuqviz.show(qc)` 一行代码内嵌 3D 播放器（断网可用），大 payload 自动降级，`as_video=True` 渲染视频内嵌
- [x] 交互式电路图：`export_html(circuit=qc)` / `show(qc)` 自动绘制 SVG 量子电路图，与 Bloch 球双向联动（播放高亮当前门 / 点击门跳转）
- [x] 内置算法库 + CLI demo：12 个经典量子算法（Bell/GHZ/Grover/QFT/QPE/Deutsch-Jozsa/Bernstein-Vazirani/隐形传态/超密编码/Simon/量子游走/叠加态），`gpuqviz demo --algo grover` 一行命令演示，支持 qiskit/pyqpanda 引擎切换
- [ ] CUDA-GL interop 零拷贝读回（当前 pinned memory）
- [ ] QASM 电路文件直接输入
- [ ] 更多国内模拟器适配（QPilotMachine / QCloud 等）
- [ ] 变分算法（VQE/QAOA）与 Shor/HHL 等大规模算法

## License

Apache-2.0
