uniqc 线路可视化重设计 · 候选设计稿

四种候选视觉风格（活渲染、可调参数）＋ 自研字符画 ＋ quantikz/LaTeX 导出 ＋ 用户调用 API 设计 ＋ 决策清单。 本稿只做设计，不动 uniqc/ 生产代码；你逐项决策后，实现另行开工。

目标质量线：至少对齐 qiskit（QuantumCircuit.draw('mpl')）与 LaTeX quantikz 的语义清晰度与美观度—— 首要修复：CNOT 必须一眼看出谁是 control（● 控制点 / ⊕ 目标），参数不再藏进悬停提示。

repo UnifiedQuantum · branch feat/circuit-viz-redesign · file design/circuit-viz-redesign.html · 2026-09-19 · 离线自包含，无任何网络依赖

§0现状诊断 —— 为什么需要重做

当前实现有两套入口，各有硬伤。§2 的「现状复刻」风格可在同一演示线路上与新方案并排对比。

① 字符画 uniqc.visualization.draw() 委托外部

  • 整体委托 pyqpanda3 的 draw_qprog（visualization/circuit.py:25）—— pyqpanda3 无 cp314 wheel，Python 3.14 上字符画直接不可用。
  • 入参是 IR 字符串而不是 Circuit 对象，与 flat API 的使用习惯脱节。
  • 风格、折叠、每行 gate 数等完全不可控；OriginIR-ext 独有构造（QRAM / QIF / error channel）无法表达。

② HTML/SVG draw_html() → _schedule_to_svg 语义缺失

  • 所有门都画成写名字的矩形，多 qubit 门只是一条普通竖线连接—— CNOT 分不清 control / target（这正是本次重设计的直接动因）。
  • 参数只存在于悬停 tooltip（<title>），打印/截图后信息丢失；门名截断为 8 字符。
  • 层宽固定 88px：短门浪费空间，长参数门溢出；无折叠换行，宽线路只能横向滚动。
  • 经典线 / dagger † / controlled_by / error channel / DEF 子程序 / QIF·QWHILE 基本没有视觉表达。
结论：两套入口都保留不了「内核」——本轮重设计提出统一渲染内核（一次布局，多风格皮肤，多格式输出）， 字符画改为自研（摆脱 pyqpanda3 依赖，风格与其余模式统一），详见 §2 与 §4。

§1演示线路 —— 覆盖全量 OriginIR-ext

三套演示线路：basic（检验控制类门语义）、full_ext（全量覆盖 OriginIR-ext 的每一个特性）、 long（检验每行 gate 数折叠换行）。§2 / §3 的所有渲染共用你在这里选中的线路。

full_ext 覆盖清单 要求：全面覆盖 OriginIR-ext

§2候选风格对比（活渲染）

同一个渲染内核、五套皮肤（含「现状复刻」作对照）。所有风格共享一套核心视觉语义—— 这套语义就是本次重设计最重要的部分；先读下面的语义约定，再看风格差异。

统一视觉语义（所有风格一致；现状态不具备）

构造视觉方案构造视觉方案
CNOT / CCX控制线 ● 实心点，目标线 ⊕ 圆+十字（TOFFOLI 为 ●●→⊕） MEASURE仪表弧符号，虚线箭头 → 双线经典线 c[k]
CZ / CP / CU控制 ● + 目标端 ●（相位类）；CU/受控旋转为目标方框+控制点 RESET|0⟩ 方框
SWAP×—× 交叉符号 BARRIER竖直虚线+端帽
ISWAP/ECR/XX/YY/ZZ/XY/PHASE2Q/UU15跨双线高盒（qiskit RZZ 风格）＋参数内嵌 dagger门名右上角 †
controlled_by在原有符号上追加控制点（不改门本体画法） error channel虚线幽灵盒＋通道名/强度（印刷风为斜线填充）
QRAM跨 addr+data 线高盒，内部虚线分隔地址/数据段 DEF/ENDDEF跨线双线边框盒（折叠态），显示子程序名
QIF/QELSE/QWHILE顶部方括号区域＋条件表达式标签（现代风附背景着色） 经典指令 AND/OR/XOR/MOV/NOT经典线上的小方盒（dest←srcs）
符号参数直接显示 θ / α₂ / 2θ+φ/3（π 倍数可切换为 π/4 形式） 多参数门参数换行内嵌；UU15 等超长参数折叠为 UU15(15p)，悬停/点击看全量
点击任意门 → 右侧看详情（交互模式雏形）
门详情（interactive 模式雏形）
尚未选中任何门。

任何风格下点击图中门/指令，这里都会显示其 opcode 细节——这就是未来 c.draw("interactive") 的核心交互：悬停高亮、点击看参数与原文。

同一 basic 线路 · 五风格静态对照

免去切换的并排对比（fold/方向等仅作用于上方主视图）。

§3自研字符画 & quantikz/LaTeX 导出

字符画将摆脱 pyqpanda3（py3.14 可用），与图形模式共用同一布局逻辑与语义符号；LaTeX 模式输出 quantikz 源码，与风格 A（Quantikz 学术风）一一对应。两者都是活渲染——跟随 §1 选择的演示线路。

① 自研字符画 新


    

      
构造Unicode纯 ASCII 回退构造Unicode纯 ASCII 回退

      
控制点●*
          CNOT 目标⊕(+)

      
量子线──--
          经典线══==

      
竖直连接│|
          SWAP×x

      
barrier┊:
          测量落线║ ╪|| #

      
门盒┤RX(θ)├|RX(t)|
          噪声通道~┤Dep(0.01)├~|Dep(.01)|

    

    
终端默认 Unicode（现代终端均支持），CI / 老 shell / 邮件场景可切纯 ASCII。终端宽度自适应：
       shutil.get_terminal_size() 决定默认折叠宽度。所有符号严格锚定列中点，跨行对齐。

  


  

    
② PNG 位图 —— 真实位图样张 新

    
以下不是示意，而是本页渲染内核的真实输出：basic 线路 → SVG → 光栅化（2× 分辨率）
       生成的 PNG 原样内嵌。即未来 c.draw("png", scale=2) 的出图效果。（重新生成：
       python design/gen_preview_assets.py）

    

      
A · Quantikz 学术风
png-quantikz

      
B · Qiskit-mpl 经典风
png-qiskit

      
C · 现代 Web·IDE 风（深色）
png-modern

      
D · 印刷·灰度风
png-print

    

  


  

    
③ quantikz LaTeX —— 编译后忠实呈现 新

    
左图由 TeX Live 2026 + quantikz.sty 真实编译下方生成器输出的源码（pdflatex → PDF → PNG 裁剪），
       即 c.draw("latex") 返回源码的忠实呈现；右栏源码实时跟随 §1 的演示线路（编译样张固定为 basic）。

    

      
quantikz 编译成品（basic 线路）
quantikz-compiled

      

    

    
quantikz 没有原生的 QIF/QWHILE/经典指令/误差通道语法——导出时这些构造退化为 % 注释 +
       占位门（dashed/double 样式），保证导出永远可编译，表达力受限处显式标注。

  







  
§4用户调用 API 设计稿

  
一个入口 Circuit.draw()，十种输出形态；旧的 uniqc.visualization.draw / draw_html 映射为兼容包装。
     以下是设计稿——命名与默认值都在 §5 决策清单里留给你定夺。


  

    
调用形态总览

    

  


  

    

      
返回值与显示行为约定

      

        
模式返回终端Jupyter

        
textstr直接打印等宽显示

        
svgstr（SVG）写文件或 filename富显示（SVG 内联）

        
pngbytes写文件富显示（图片）

        
mplFigure—富显示（可再编辑）

        
latexstr（quantikz 源码）打印/写文件代码块

        
htmlstr（自包含 HTML）写文件iframe 富显示

        
interactive同 html + JS写文件（浏览器打开）iframe 富显示

      

      
Circuit 同时新增 _repr_svg_（Jupyter 里 c 回车即出图）与
        __str__（终端里 print(c) 即字符画）——与 qiskit 的体验对齐。

    

    

      
依赖策略（不新增硬依赖）

      

        
能力依赖说明

        
text / svg / html / interactive纯 stdlib核心卖点：默认安装即可视化，含 py3.14

        
png可选：matplotlib 或 cairosvg自动探测；都没有则提示安装其一

        
mplmatplotlib（已有 [visualization] extra）复用现有 extra

        
latex无（返回源码）编译为图片属可选增强（需本地 LaTeX）

        
旧 draw（pyqpanda3 文本）pyqpanda3降级为 opt-in：style="qpanda"，缺失时回退自研

      

    

  


  

    
旧 API → 新 API 映射（兼容策略）

    

      
现状问题新设计

      
uniqc.visualization.draw(ir_str, language=)入参是 IR 字符串；委托 pyqpanda3
          接受 Circuit | IR 字符串 | JSON；默认自研字符画；pyqpanda3 风格 style="qpanda" opt-in

      
uniqc.visualization.draw_html(...)无样式/无折叠/语义缺失
          c.draw("html", style=...)；旧函数保留为薄包装并按 0.0.x 弃用政策加 DeprecationWarning

      
uniqc.compile.draw / timeline.circuit_to_html重复出口
          统一收敛到 uniqc.visualization.render(circuit, mode=..., style=...)；旧出口转兼容 wrapper

    

    
CLI 同步：uniqc circuit draw <file> --mode svg|text|png|html --style quantikz|qiskit|modern|print --fold 20 -o out.svg

  







  
§5决策清单 —— 请逐项拍板

  
点选后下方会实时生成一份决策摘要，全选完复制发我即可进入实现阶段。

  

  

    
决策摘要（复制回复给我）

    
（尚未选择）

  







  
§6实现路线图（决策后开工，本轮不动代码）

  

    

      
阶段内容验收

      
P1 内核uniqc/visualization/renderer/：布局引擎（分层/列宽/折叠）+ SVG 原语序列化 + 语义分类（●/⊕/跨线盒/…）
          全量 OriginIR-ext 构造 × 4 风格渲染快照测试

      
P2 文本自研字符画（unicode/ascii 双符号集、终端宽度自适应折叠）test_endianness_convention 风格的单测；py3.14 可用

      
P3 导出quantikz 源码 / html / interactive；png（matplotlib·cairosvg 自动探测）quantikz 源码编译冒烟（CI 可选）

      
P4 接线Circuit.draw() + _repr_svg_ / __str__ + CLI circuit draw + 旧 API 兼容包装
          全测试套件 + 文档 make html（example-exec-logs 同步）

      
P5 文档新示例 examples/1_basic_usage/（含确定性种子）+ API 文档docs 构建无警告

    

    
每阶段独立 PR；P1 确定后风格皮肤（§2 决策）为纯数据配置，可并行迭代。