gpuqviz 0.5.0__tar.gz

gpuqviz-0.5.0/.gitattributes

@@ -0,0 +1,5 @@
+* text=auto eol=lf
+*.png binary
+*.bin binary
+*.npz binary
+*.mp4 binary

gpuqviz-0.5.0/.github/workflows/ci.yml

@@ -0,0 +1,95 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    strategy:
+      fail-fast: false # 一个 OS 失败不取消另一个，便于对照
+      matrix:
+        os: [ubuntu-latest, windows-latest]
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+      # ubuntu 无显示环境：装 headless GL 系统库，
+      # moderngl standalone context 经 EGL/Mesa 可用
+      - name: Install headless GL (ubuntu)
+        if: runner.os == 'Linux'
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y libegl1 libgl1 libosmesa6
+      - name: Install (CPU-only extras; GPU extras need CUDA runners)
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e .[qiskit,cpu-fallback,dev]
+      - name: Lint
+        run: |
+          ruff check src tests examples benchmarks scripts
+      - name: Test
+        env:
+          QT_QPA_PLATFORM: offscreen
+        run: |
+          python -m pytest tests -q -k "not gpu_only" --tb=short 2>&1 | tee pytest_output.txt
+          exit ${PIPESTATUS[0]}
+      - name: Failure diagnostics → step summary
+        if: failure()
+        run: |
+          echo "### pytest 失败摘要（${{ matrix.os }}）" >> "$GITHUB_STEP_SUMMARY"
+          tail -n 60 pytest_output.txt >> "$GITHUB_STEP_SUMMARY" || true
+      - name: Upload test log (failure diagnostics)
+        if: ${{ failure() }}
+        uses: actions/upload-artifact@v4
+        with:
+          name: pytest-${{ matrix.os }}
+          path: pytest_output.txt
+      # 无 NVIDIA GPU：NVENC/NV12 用例自带 skipif；cupy 用例模块级
+      # importorskip 跳过；GPU 采样基准标记 gpu_only 不在 CI 跑。
+
+  # S8: 无 GPU 环境可移植性回归门禁——强制 CPU 后端完整出片
+  # （ubuntu runner 不装 CUDA/cupy，模拟零硬件用户的实际环境）
+  cpu-portability:
+    runs-on: ubuntu-latest
+    env:
+      GPUQVIZ_BACKEND: cpu
+      QT_QPA_PLATFORM: offscreen
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+      - name: Install (CPU-only, no GPU extras)
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e .[qiskit,cpu-fallback,dev]
+      - name: CPU backend bell + heatmap video
+        run: |
+          python - <<'PY'
+          import av, os
+          from qiskit import QuantumCircuit
+          from gpuqviz import render_bloch_video, render_heatmap_video
+          from gpuqviz.backends import detect_backend
+          assert detect_backend() == "cpu", f"expected cpu, got {detect_backend()}"
+          qc = QuantumCircuit(2); qc.h(0); qc.cx(0, 1)
+          # bell 2s@30fps
+          out1 = render_bloch_video(circuit=qc, steps=20, fps=30, seconds=2,
+                                     out="out/cpu_bell.mp4", backend="cpu")
+          with av.open(str(out1)) as c:
+              n1 = sum(1 for _ in c.decode(video=0))
+          assert n1 == 60, f"bell: expected 60 frames, got {n1}"
+          assert os.path.getsize(out1) > 1000
+          # ghz heatmap 2s@30fps
+          qc3 = QuantumCircuit(3); qc3.h(0); qc3.cx(0,1); qc3.cx(1,2)
+          out2 = render_heatmap_video(circuit=qc3, steps=20, fps=30, seconds=2,
+                                       out="out/cpu_heatmap.mp4", backend="cpu")
+          with av.open(str(out2)) as c:
+              n2 = sum(1 for _ in c.decode(video=0))
+          assert n2 == 60, f"heatmap: expected 60 frames, got {n2}"
+          assert os.path.getsize(out2) > 1000
+          print(f"CPU portability: bell={n1}f, heatmap={n2}f — PASS")
+          PY

gpuqviz-0.5.0/.github/workflows/release.yml

@@ -0,0 +1,45 @@
+name: Release to PyPI
+
+# tag 触发（v*）；也可在 GitHub Releases 页面手动发布
+on:
+  push:
+    tags: ["v*"]
+  workflow_dispatch: # 支持手动触发（选 tag）
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+      - name: Build sdist + wheel
+        run: |
+          python -m pip install --upgrade pip build
+          python -m build
+      - name: Check artifacts
+        run: |
+          python -m pip install twine
+          python -m twine check dist/*
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi # PyPI Trusted Publisher 里配置的 environment 名
+    permissions:
+      id-token: write # OIDC：Trusted Publishing 必须
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

gpuqviz-0.5.0/.gitignore

@@ -0,0 +1,22 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.venv/
+.mypy_cache/
+.ruff_cache/
+.pytest_cache/
+.coverage
+
+# 渲染输出
+out/
+*.mp4
+
+# IDE
+.idea/
+.vscode/
+
+# ZCode 会话工作文件
+.zcode/

gpuqviz-0.5.0/.zcodeignore

@@ -0,0 +1,49 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.venv/
+.mypy_cache/
+.ruff_cache/
+.pytest_cache/
+.coverage
+
+# 渲染输出
+out/
+*.mp4
+
+# IDE
+.idea/
+.vscode/
+
+# ===== ↑ 以上同步自 .gitignore（「从 .gitignore 同步」只重写以上部分）=====
+.git/
+.hg/
+.svn/
+node_modules/
+bower_components/
+jspm_packages/
+site-packages/
+venv/
+coverage/
+htmlcov/
+lcov-report/
+cmakefiles/
+cmake-build-*/
+bazel-*/
+pods/
+deriveddata/
+storybook-static/
+playwright-report/
+test-results/
+allure-results/
+allure-report/
+cdk.out/
+*.dist-info/
+eggs/
+pip-wheel-metadata/
+wheels/
+# ----- ↑ 以上为 ZCode 默认排除规则（自定义规则请写在本行下方，不会被同步/恢复改动）-----
+# 自定义规则写在下方（本行提示可删除）

gpuqviz-0.5.0/CHANGELOG.md

@@ -0,0 +1,168 @@
+# Changelog
+
+## 未发布（内置算法库 + CLI demo + 引擎切换）
+
+- **CLI `demo` 命令**：`gpuqviz demo --algo grover` 一行命令演示内置算法
+  - `--list`：列出全部 12 个算法及简介
+  - `--format html|mp4|png`：交互式播放器 / 视频 / 静态帧
+  - `--engine qiskit|pyqpanda`：模拟引擎切换（默认 qiskit）
+  - `--n-qubits`/`--steps`/`--fps`/`--seconds`/`--style`/`--trail`/`--time`：可视化参数
+  - qiskit/pyqpanda 未安装时优雅提示安装命令
+  - pyqpanda 引擎自动管理 QVM 生命周期（init_qvm/qAlloc/finalize）
+- **`gpuqviz.algorithms` 模块**：12 个经典量子算法电路构建器
+  - 基础态：`bell()`、`ghz(n)`、`superposition(n)`
+  - 搜索：`grover(n, marked, iterations)`（统一原有两个不一致实现）
+  - 变换：`qft(n, inverse=False)`
+  - 估计：`phase_estimation(n_count, theta)`
+  - 查询复杂度：`deutsch_jozsa(oracle_type, n)`、`bernstein_vazirani(secret)`、`simon(s, n)`
+  - 通信：`teleportation()`、`superdense(message)`
+  - 游走：`quantum_walk(n, steps)`
+  - 每个算法接受 `engine="qiskit"|"pyqpanda"|"numpy"` 参数
+  - 注册表 `ALGORITHM_REGISTRY` + `get_algorithm(name)` + `list_algorithms()`
+  - 包级导出：`from gpuqviz import algorithms` / `from gpuqviz.algorithms import grover`
+- **引擎切换架构**：`engine` 参数贯穿 CLI → 算法库 → 可视化 API
+  - qiskit（默认）：QuantumCircuit → sample_circuit / evolve_gates
+  - pyqpanda：QProg → ORIGINIR → numpy（CLI 自动创建 CPUQVM）
+  - numpy（保留扩展）：list[Gate] → evolve_gates（无外部依赖）
+- **测试**：`tests/test_algorithms.py`（45 例：注册表完整性、每个算法 qiskit/numpy
+  路径一致性、数值正确性验证——Bell 末态、GHZ 纠缠、Grover 振幅放大、QFT†∘QFT=I、
+  QPE 相位编码、DJ 常数/平衡判定、BV 秘密恢复、隐形传态态转移、超密编码消息解码、
+  Simon 电路一致性、量子游走一致性、引擎参数验证）
+- **示例**：`examples/algorithms_demo.py`（遍历 12 个算法批量生成 HTML 演示）
+- **文档**：README 新增"内置算法库"小节 + CLI demo 用法 + roadmap 勾选；
+  `docs/api.md` 新增 `gpuqviz.algorithms` 命名空间与 CLI demo 参数说明
+
+## 未发布（交互式电路图 + Bloch 球联动）
+
+- `export_html(circuit=qc)` / `show(qc)` 自动在播放器顶部绘制 **SVG 量子电路图**，
+  与 3D Bloch 球双向联动
+  - 浏览器端纯 JavaScript 生成 SVG（无外部电路绘制库依赖），支持单量子门方框、
+    受控门（控制点 + ⊕ 目标符）、SWAP（× 符号）、ISWAP（跨行方框）、参数门标签
+    （`RX(π/2)` 等角度格式化）、UNITARY（U 方框）
+  - 播放时自动高亮当前正在执行的门（橙色 `--accent2`）；点击电路图中的门
+    跳转到该门对应时刻，Bloch 球与状态面板同步更新
+  - 门-关键帧精确对齐：`circuit` 输入时改用 `evolve_gates` + `sample_snapshots`
+    路径采样（与 `sample_circuit` 数值一致），每个关键帧天然对应一个门
+  - payload 新增 `circuit` 字段：`{n_qubits, n_ops, gates[], active_gates[],
+    gate_times[]}`（`export_html._build_circuit_info`）
+  - 优雅降级：states-only 输入 / pyqpanda 翻译失败时隐藏电路面板，其余功能不受
+    影响；降级模式（>8MB）保留 `circuit` 字段（体积小）
+- `viewer_template.html`：新增 `#circuitPanel` DOM 节点 + 电路图 SVG 样式
+  （wire / gate-box / control-dot / target-circle / swap-cross / active 高亮）
+- `viewer.js`：新增 `buildCircuitDiagram()` / `updateCircuitHighlight()` /
+  `seekToGate()`，`Init` 构建电路图，`renderFrame` 每帧更新高亮
+- `jupyter.py`：`show(circuit=qc)` 路径同步使用 `evolve_gates` 采样 +
+  `circuit_info` 附加 payload
+- 测试：`tests/test_circuit_viewer.py`（18 例：门标签格式化、Bell/GHZ 门元数据、
+  active_gates/gate_times 映射、HTML 包含电路图元素、降级保留 circuit、
+  viewer.js 函数存在、show() 集成）
+- 文档：README 交互式播放器段落增述电路图联动，Roadmap 勾选
+
+## 未发布（S9 Jupyter 交互集成）
+
+- `gpuqviz.show(circuit=None, states=None, scene=None, steps=60, out=None,
+  as_video=False, height=520, **kwargs)`：一行代码在 Jupyter notebook 中内嵌
+  交互式 3D 播放器（`src/gpuqviz/jupyter.py`）
+  - 环境检测：`_is_notebook()` 检查 `IPython.get_ipython()` 是否为 ZMQ 内核
+    （notebook / JupyterLab / qtconsole），终端回退写 HTML 文件
+  - notebook 内：复用 `export_html` payload 构建，生成自包含 HTML（three.js
+    内联，断网可用），通过 `IPython.display.HTML` 以 iframe `srcdoc` 内嵌，
+    `height` 可调
+  - payload 降级：超 8MB 时自动剥离 `states_re`/`states_im`（只保留 Bloch
+    向量），文件从 ~8.7MB 降至 ~0.7MB 并发 `RuntimeWarning`
+  - `as_video=True`：先渲染 MP4 再用 `IPython.display.Video` 内嵌
+- `viewer.js` 降级兼容：`states_re` 为 null 时 `updatePanel` 跳过概率条更新、
+  `renderFrame` 跳过态矢量插值，只显示 Bloch 向量
+- 包级入口：`__init__.py` 导出 `show`（惰性 import，未装 IPython 不影响
+  `import gpuqviz`）
+- 测试：`tests/test_jupyter.py`（11 例：非 notebook 写文件、payload 数值正确、
+  降级触发/不触发、`_strip_state_panel`、viewer.js null guard、环境检测、
+  nbconvert 执行最小 notebook smoke）
+- 文档：README 新增"Jupyter 交互集成"小节（show 示例 + 参数说明），
+  `docs/api.md` 增补 `show` 签名与后端/ Jupyter 小节
+
+## 未发布（S8 CPU/无 GL 环境可移植性 + NVENC 修复）
+
+- NVENC 修复：`NvencEncoder` 重写适配 PyNvVideoCodec 2.x API（`FFmpegMuxer`
+  完整参数构造 + `MuxVideoPacket` + `Finalize` + `SetUniformPtsIncrement`），
+  CAIMemoryView 显存直喂失败（error 8）改用 `usecpuinputbuffer=True` + cupy
+  GPU NV12 kernel + `asnumpy` 路径；`nvenc_available()` 探测改隔离子进程避免
+  原生崩溃杀宿主。性能：cupy GPU NV12（787 fps）+ NVENC 硬件编码（236 fps）
+  端到端 141 fps @1080p，比 libx264 快 3.8×（此前 numpy CPU NV12 路径为瓶颈）
+- CPU 软光栅重写（`backends/cpu.py`）：包围盒光栅（不再每帧全屏距离场）+
+  numba `@njit(parallel=True, cache=True)` 加速圆盘/圆环/椭圆环/线段/热图LUT/
+  相位色盘热路径，numba 缺失时静默回退 numpy。CPU bell 3s@30fps 720p 从
+  116.3s 降至 ~6s（19× 加速），远超 ≤20s 目标
+- CPU 后端补齐：新增 `SoftRasterHeatmap`（LUT 伪彩，与 GL 路径数值一致）、
+  `draw_text`（PIL ImageDraw + ImageFont，支持系统字体回退）、`draw_phase_disc`
+  （HSV→RGB 相位色盘 CPU 版）；`render_heatmap_video` 支持 `backend="cpu"`，
+  `render_frame` CPU 路径支持 scene（bloch+heatmap+title）
+- GL 降级链（`render/context.py`）：`create_gl_context` 先试 GL 3.3 再降 3.2，
+  每次降级打印决策日志，全部失败抛 `GLUnavailableError`；新增
+  `GLUnavailableError` 异常类型
+- 环境变量 `GPUQVIZ_BACKEND`（auto/gl/cpu）强制指定后端，优先级高于
+  `detect_backend()` 自动探测和调用方 `backend` 参数默认值；`detect_backend`
+  和 `resolve_backend` 尊重环境变量
+- `report_env()` 新增"实际渲染路径"列（显示 `GPUQVIZ_BACKEND` 或探测结果）；
+  NVENC 探测改用隔离子进程 `nvenc_available()`
+- CI：新增 `cpu-portability` job（ubuntu-latest，不装 CUDA，`GPUQVIZ_BACKEND=cpu`
+  下 `render_bloch_video` + `render_heatmap_video` 各出 2s 小视频并用 PyAV
+  校验帧数，作为可移植性回归门禁）；test job 安装 `cpu-fallback` extras
+- 测试：`tests/test_cpu_portability.py`（10 例：环境变量后端选择、CPU 软光栅
+  基元、热图 LUT 查表、CPU 热图出片、CPU render_frame PNG、CPU GHZ 多球）
+- 基准：`benchmarks/suite.py` 重写，新增 CPU 优化前后对照行；
+  `docs/benchmarks.md` 更新
+
+## 未发布（S7 布局/样式系统 + 出版级静态图）
+
+- 样式系统扩展：`STYLES` 新增 `bw`（论文黑白：纯白背景、黑轴、灰球壳、深灰矢量）
+  与 `poster`（高对比度深底 + 暖色矢量）预设；`style` 参数支持 str 预设名或 dict，
+  新增 `style_overrides` 参数按 merge 语义覆盖任意键（如 `{"vector_color": (1,0,0)}`）
+- 布局系统：`render_bloch_video` 新增 `cols`（一行最多几个球，语义对齐 recorder
+  的 `num_cols`）与 `figsize`（英寸元组，dpi=100 换算像素，与默认 1920×1080 互斥）；
+  多行布局行距自适应，相机距离取行列包络；CPU 后端同步支持 `cols` 网格
+- 出版级静态图：`render_frame(circuit|states|scene, t, out, scale, style, cols, figsize)`
+  渲染归一化时刻 t∈[0,1] 的单帧 → PNG，`scale` 超采样（2/4×）抗锯齿，
+  内部以 scale×分辨率 GL 渲染后 PIL LANCZOS 缩回目标尺寸；等效 300dpi 输出
+  方式：`figsize=(英寸,)` 指定像素数 = 英寸 × 100（再乘 scale 做超采样）
+- CLI：`gpuqviz frame --scene xxx.json | --states xxx.npz --time 0.5 --scale 2 -o fig.png`
+- 依赖：新增 `Pillow>=10.0`（PNG 编码）
+- 测试：`tests/test_layout.py`（8 例：预设完整性、覆盖语义、figsize 换算、
+  单行/多行/单列布局包围盒不重叠）+ `tests/test_frame_export.py`（7 例：
+  PNG 尺寸正确、非纯色、bw 白底、scale 抗锯齿、t 越界报错、style_overrides）
+- 示例：`examples/publication_fig.py`（Bell bw 3200×2000 scale=4、8-qubit GHZ
+  cols=2 多行、Bell dark 中间时刻）
+
+## 未发布（S6 高层门/复杂电路兼容性）
+
+- 门级模拟器扩展：通用矩阵作用原语 `_apply_matrix`、多控制门构造 `_controlled`、
+  U/U1/U2/U3/P/PHASE、受控参数门 CRX/CRY/CRZ/CH/CU、任意控制位 MCX/MCP/Toffoli、
+  ISWAP、SDG/TDG
+- `adapters.qiskit_to_gates`：qiskit QuantumCircuit → 框架无关 Gate 列表的翻译器，
+  优先命名直译 → `to_matrix`/`Operator` 矩阵路径 → `definition` 递归展开 →
+  `transpile` 到基础门集兜底（未知指令也能出片）
+- 态矢量路径对中途 `measure`/`reset`/`delay` 的处理：自动跳过并提示，
+  `measure_all` 自动剔除（不再触发 `Cannot apply instruction with classical bits`）
+- ORIGINIR 解析扩展：TOFFOLI/CCX、ISWAP、U1/U2/U3/P、CRZ/CH/CU3
+- `encode.nvenc_available` 探测改为隔离子进程执行：Pascal EOL 驱动上
+  `nvEncOpenEncodeSessionEx` 触发的原生 access violation 不再杀死宿主进程，
+  结果进程内缓存
+- 测试：新增 `tests/test_gates_matrix.py`，14 个电路（Bell/GHZ3/QFT/mcx oracle/
+  受控参数门全家/StatePreparation/measure/UnitaryGate/global phase/barrier/
+  自定义门/嵌套定义/cu+mcp/4-qubit mcx 链）对 qiskit Statevector 末态保真度
+  全部 ≥ 1-1e-9；1:1 翻译电路逐层快照逐帧一致
+- 示例：`examples/grover_mcx.py`（3-qubit 含 mcx 的两轮 Grover，目标态 |101⟩
+  振幅放大至 0.945，出片 `out/grover.mp4`）
+
+## 0.1.0 (2026-09-13)
+
+首个可用版本。
+
+- 零落盘渲染管线：moderngl 离屏 FBO → 进程内 PyAV 编码（h264_nvenc 探测回退 libx264）
+- `render_bloch_video` / `render_heatmap_video` / Scene 声明式 API（JSON 持久化 + CLI）
+- 布洛赫球（Phong 球壳/轨迹/多 qubit）、概率热图（viridis/inferno）、相位色盘、SDF 中文字幕
+- qiskit 电路采样（按深度分层）+ 批量 einsum Bloch 向量 + slerp 关键帧插值（含对跖点）
+- NVENC 显存直喂路径（PyNvVideoCodec + cupy RGBA→NV12 kernel），会话探测失败自动回退
+- CPU 软光栅后端（numpy，limited 样式），无 OpenGL 环境自动降级
+- 规避的兼容性问题：fbo.read() 全零（改读颜色附件）、色表 REPEAT 边缘混色（clamp）、
+  矩阵行/列主序、qiskit 小端序 Bloch 索引、freetype SDF 过渡宽度量纲

gpuqviz-0.5.0/DESIGN.md

@@ -0,0 +1,240 @@
+# gpuqviz — GPU 加速量子态演化可视化视频渲染库 · 方案设计
+
+> 目标：替代 `qiskit-state-evolution-record` 的 CPU 逐帧渲染流水线，把 15s 视频的渲染时间从 30+ 分钟压缩到 **1~3 分钟以内**（数量级提升来自：GPU 光栅化 + GPU 上传/合成 + NVENC 硬编码 + 消除逐帧写盘）。
+
+---
+
+## 1. 现状瓶颈分析
+
+典型 CPU 流水线（qiskit-state-evolution-record 类库）的每帧路径：
+
+```
+Statevector (CPU) → matplotlib 画布渲染 (~2-10s/帧) → PNG 编码落盘 → ffmpeg 软编码读盘
+```
+
+三大瓶颈：
+
+| 瓶颈 | 原因 | 占比（估计） |
+|---|---|---|
+| matplotlib 逐帧绘制 | CPU 光栅化、每帧重建 Figure、抗锯齿全在 CPU | ~70% |
+| 逐帧写盘 PNG | 磁盘 IO + PNG 压缩编码 | ~15% |
+| CPU 软编码 + 读盘 | x264/libx264 编码、再次 IO | ~15% |
+
+## 2. 新流水线设计
+
+```
+qiskit Circuit/Statevector
+   │  (一次性，CPU 上仿真或 GPU 上演化)
+   ▼
+关键帧态矢量序列 [ψ(t₀), ψ(t₁), ...]  ── GPU 间插值/演化（CuPy）
+   │  常驻显存，不落盘
+   ▼
+GPU 渲染层（ModernGL / VisPy，离屏 FBO）：
+   ├─ 布洛赫球（球体网格 + 相机 + 深度测试）
+   ├─ 量子态波函数/概率幅热图（纹理 + 片元着色器）
+   ├─ 相位色环、坐标轴、标注（线框 + SDF 文字）
+   │  关键帧之间由顶点/片段着色器插值，实现任意帧率平滑动画
+   ▼
+FBO 像素 → NVJPEG/CUDA 直接取回或零拷贝进编码器
+   ▼
+NVENC 硬编码（PyNvVideoCodec 或 PyAV + h264_nvenc）→ MP4
+```
+
+核心原则：
+1. **帧不落盘**：渲染帧直接进编码器（pinned memory / CUDA IPC）。
+2. **插值在 GPU**：只算 N 个关键帧态矢量，中间帧由着色器插值生成，CPU 仿真次数与输出帧率解耦。
+3. **复用 GL 上下文与网格资源**：初始化一次，逐帧只更新 uniform/纹理。
+
+## 3. 技术栈与引用的开源库
+
+| 层 | 选型 | 理由 |
+|---|---|---|
+| 量子仿真 | `qiskit` + `qiskit-aer`（可选用 `qiskit-aer-gpu`） | 与现有工作流兼容；Aer-GPU 可让态矢量演化也在 GPU |
+| GPU 数组/演化 | `cupy`（CUDA 12.x） | 态矢量操作、插值、概率计算全部在 GPU；API 近似 NumPy |
+| GPU 渲染 | `moderngl`（离屏渲染，首选） + `moderngl-window`（可选交互预览） | 轻量、无需窗口即可渲染到 FBO；比 VisPy 更底层可控，比 PyOpenGL 省事 |
+| 文字/标注 | `freetype-py` + 自制 SDF 字形图集 | GL 里高质量渲染中文/数学标注 |
+| 数学网格 | `trimesh`（生成布洛赫球、坐标轴网格，预处理一次） | 生成球体/圆环 obj，运行时上传 VBO |
+| 视频编码 | `pynvvideocodec`（NVIDIA 官方 Python 绑定 NVENC，首选）；回退 `PyAV` + `h264_nvenc`/`hevc_nvenc` | 帧数据可留在 GPU 显存直接喂编码器，实现零落盘 |
+| CPU 回退路径 | `numpy` + `pygame/SDL` 软渲染 + PyAV x264 | 无 NVIDIA GPU 时仍可用（比旧库快，因无 matplotlib 开销） |
+| 配置/CLI | `pydantic` + `typer` | 场景描述用 pydantic 模型，CLI 用 typer |
+| 测试 | `pytest` + `pytest-mock`；渲染用像素哈希对比 | 回归测试 |
+| 打包 | `pyproject.toml` (hatchling) + 可选 `nvidia-*` wheel 依赖 | pip 一键装 |
+
+明确**不用**的东西：
+- ❌ matplotlib（慢的根源；如需静态图保留一个导出接口即可）
+- ❌ 逐帧 PNG 中间文件
+- ❌ ffmpeg 子进程管道（PyAV/PYNVVIDEOCODEC 进程内编码，省 IO 与序列化）
+
+## 4. 包结构
+
+```
+gpuqviz/
+├── pyproject.toml
+├── README.md
+├── src/gpuqviz/
+│   ├── __init__.py            # 导出公开 API
+│   ├── scene.py               # Scene / Track / 关键帧模型 (pydantic)
+│   ├── evolve.py              # 量子演化：qiskit circuit → 关键帧态矢量（CuPy 数组）
+│   ├── render/
+│   │   ├── context.py         # 隐藏 GL 上下文/设备管理、离屏 FBO 封装
+│   │   ├── bloch.py           # 布洛赫球 renderer（多 qubit 网格布局）
+│   │   ├── heatmap.py         # 波函数/概率热图 renderer（GPU 纹理）
+│   │   ├── phasesphere.py     # 相位色环/幅值柱 renderer
+│   │   ├── text.py            # SDF 文字渲染
+│   │   └── compositor.py      # 多 renderer 合成到同一帧（framebuffer 混合）
+│   ├── interpolate.py         # GPU 关键帧插值（slerp 四元数 / 态矢量线性插值+归一化）
+│   ├── encode.py              # NVENC / PyAV 编码器抽象（帧 GPU 内存直入）
+│   ├── pipeline.py            # 顶层编排：evolve → render loop → encode
+│   ├── preview.py             # moderngl-window 实时预览（可选）
+│   └── backends/
+│       ├── cuda.py            # CuPy/CUDA 路径
+│       └── cpu.py             # numpy 回退路径
+├── examples/
+│   ├── bell_state_bloch.py
+│   └── ghz_heatmap.py
+└── tests/
+```
+
+## 5. 公开 API 设计
+
+### 5.1 快捷函数（覆盖 90% 用例）
+
+```python
+import gpuqviz
+
+# 一行出片：qiskit 电路 → 布洛赫球动画 MP4
+gpuqviz.render_bloch_video(
+    circuit=qc,                # qiskit.QuantumCircuit；无参演化（按电路层推进）
+    steps=120,                 # 电路均匀采样 120 个关键帧
+    fps=60,                    # 输出帧率（关键帧间 GPU 插值到 60fps）
+    out="bell.mp4",
+    style="dark",              # 预设主题
+    codec="h264",              # h264 / hevc，NVENC 硬编码
+)
+
+# 从 Statevector 序列出片（用户自己演化也行）
+gpuqviz.render_heatmap_video(
+    states=[psi0, psi1, ...],          # qiskit.quantum_info.Statevector 序列
+    fps=30, out="evol.mp4",
+)
+```
+
+### 5.2 声明式 Scene API（可组合、可持久化为 JSON）
+
+```python
+from gpuqviz import Scene, BlochTrack, HeatmapTrack, Camera, render
+
+scene = Scene(
+    width=1920, height=1080, fps=60, duration=8.0,   # 秒
+    background="#0b0e14",
+)
+scene.add(BlochTrack(
+    states=statevectors,        # 关键帧（qiskit Statevector 或 cupy 数组）
+    qubit_indices=[0, 1],       # 多 qubit 各一个球
+    trail=True,                 # 显示轨迹尾巴
+))
+scene.add(HeatmapTrack(
+    states=statevectors,
+    basis="probability",        # probability / amplitude / phase / real / imag
+))
+scene.camera = Camera(orbit=(azimuth=(0, 90), elevation=(20, 35)))  # 相机动画
+render(scene, "out.mp4", codec="hevc", quality=0.9)
+```
+
+### 5.3 底层 API（逐帧回调，完全可控）
+
+```python
+from gpuqviz import Renderer, Encoder, GLContext
+
+with GLContext(width=1920, height=1080, device=0) as gl:
+    enc = Encoder("out.mp4", fps=60, codec="hevc_nvenc")  # 常驻编码器
+    for t, frame_gpu in gl.frame_iterator(total_frames=480):
+        # frame_gpu: cupy ndarray (H,W,4) uint8，显存中
+        ...  # 自定义绘制，或调用内置 renderer
+        enc.write(frame_gpu)          # 显存直入 NVENC，零落盘
+    enc.close()
+```
+
+### 5.4 与 qiskit 的衔接点
+
+- `evolve.py` 内部用 `qiskit.quantum_info.Statevector(circuit)` + 逐步分解（对电路按层截断得到关键帧），或接受 `qiskit-aer` 的 `save_state` 结果。
+- 可选：检测到 `qiskit-aer-gpu` 时把 `AerSimulator(method="statevector", device="GPU")` 用于演化本身。
+- 输入协议：任何能转 `numpy/cupy 复数向量 (2^n,)` 的对象都可以（qiskit `Statevector`、`DensityMatrix`、自定义数组），对 qiskit 仅软依赖（extras：`pip install gpuqviz[qiskit]`）。
+
+## 6. 关键技术点
+
+1. **态矢量 → 布洛赫球**：对多 qubit 态求 `ρᵢ = Tr(ψψ† ⊗ 其余)` 得每个 qubit 的 Bloch 向量（CuPy einsum，微秒级）；帧间用球面 slerp 插值。
+2. **关键帧 → 任意帧率**：只在上游算 N 个关键帧，输出帧率与仿真解耦；60fps 输出 15s = 900 帧，其中大多数是着色器插值帧，成本可忽略。
+3. **零落盘编码**：FBO 用 `glReadPixels` 进 pinned buffer → CuPy 视图 → NVENC 输入。`pynvvideocodec` 支持 CUDA device buffer 直喂；无 NVENC 时回退 PyAV `h264_nvenc`（仍走 GPU 编码）或 libx264（最后手段）。
+4. **文字**：freetype 生成字形图集纹理一次，运行时片元着色器采样，支持中文标注。
+5. **确定性测试**：GL 渲染对同一驱动/硬件是确定的，用帧哈希做回归；跨硬件则比较结构相似度。
+
+## 7. 依赖文件（pyproject.toml）
+
+```toml
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "gpuqviz"
+version = "0.1.0"
+description = "GPU-accelerated quantum state evolution visualization and video rendering"
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "Apache-2.0" }
+dependencies = [
+    "numpy>=1.24",
+    "cupy-cuda12x>=13.0",          # GPU 数组计算
+    "moderngl>=5.10",              # 离屏 GL 渲染
+    "pynvvideocodec>=12.2.72.0",   # NVENC 硬编码（NVIDIA 官方包）
+    "PyAV>=14.0",                  # 回退/封装编码器
+    "freetype-py>=2.4",
+    "trimesh>=4.0",
+    "pydantic>=2.6",
+    "typer>=0.12",
+]
+
+[project.optional-dependencies]
+qiskit = ["qiskit>=1.0", "qiskit-aer>=0.14"]
+qiskit-gpu = ["qiskit>=1.0", "qiskit-aer-gpu>=0.14"]
+preview = ["moderngl-window>=2.4"]
+cpu-fallback = ["numba>=0.59"]
+dev = ["pytest>=8.0", "pytest-cov", "ruff", "mypy"]
+
+[project.scripts]
+gpuqviz = "gpuqviz.cli:app"
+
+[tool.ruff]
+line-length = 100
+```
+
+> 安装：`pip install gpuqviz[qiskit]`；硬件要求：NVIDIA GPU（SM ≥ 6.0，驱动 ≥ 550），CUDA 12.x。无 NVIDIA 卡时自动降级 CPU 后端。
+
+## 8. 性能预算（15s @ 60fps = 900 帧，1920×1080，单卡 RTX 3060 级别）
+
+| 阶段 | 预估 |
+|---|---|
+| 态演化 + Bloch 向量计算（120 关键帧，CuPy） | < 5 s |
+| 布洛赫球光栅化 ~0.5 ms/帧 × 900 | < 1 s |
+| 热图纹理更新 ~1 ms/帧 | ~1 s |
+| FBO 读回 (pinned) ~2 ms/帧 | ~2 s |
+| NVENC hevc 编码 1080p60 | 实时（< 8 s） |
+| **合计** | **≈ 10–20 s** |
+
+对比现状 30 分钟，预期 **100× 左右**加速。瓶颈会转移到 FBO 读回，后续可用 CUDA-GL interop（`cudaGraphicsGLRegisterImage`，经 cuda-python）进一步消除拷贝。
+
+## 9. 里程碑
+
+1. **M0（1 周）**：骨架 + GLContext/FBO + 纯色帧 → PyAV 编码出片（打通零落盘管线）。
+2. **M1（2 周）**：布洛赫球 renderer + 关键帧 slerp + qiskit 输入，`render_bloch_video` 可用。
+3. **M2（1 周）**：接入 PyNvVideoCodec 显存直喂编码；热图/相位 renderer。
+4. **M3（1 周）**：Scene 声明式 API、SDF 文字、主题、CLI。
+5. **M4（持续）**：CPU 回退后端、CUDA-GL interop 优化、文档与示例、发 PyPI。
+
+## 10. 风险与对策
+
+- **PyNvVideoCodec API 变动/仅部分格式**：Encoder 抽象层隔离，PyAV nvenc 作为等价回退。
+- **无 NVIDIA GPU 的用户**：CPU 后端（numba 并行软光栅 + libx264）保证可用性，性能仍远好于 matplotlib 方案。
+- **多 qubit 热图维度爆炸**（n>10）：限制热图到 ≤ 10 qubit，提示用约化密度矩阵/局域观测渲染。
+- **跨平台（Windows/Linux）GL 离屏**：moderngl 用 EGL/headless 在 Linux 无显示环境可用；Windows 默认 WGL，均无需窗口。