文档版本

标准实验可视化¶

使用 visualize() 可以把已有结果生成完整的独立 HTML 实验报告。报告从已经执行完成的结果派生，不会重新运行程序。

from cascaqit import visualize

report = visualize(result, program=program, output="experiment.html")

对于单个 Digital、Analog 或 Hybrid 结果，program 是可选参数；传入后，报告会同时展示程序设计。输出文件会内嵌核心 BokehJS runtime，不依赖 Web 服务或 CDN，可以直接在本地浏览器打开。报告头部提供 English / 中文语言选项，用于切换标准界面语言。坐标轴、图例、工具说明和悬停标签会一起切换，稍后加载完成的图表也会使用当前语言。切换时保留图表数据、平移缩放范围和内嵌的结果 JSON。返回的 ExperimentReport 还提供 sections、section()、to_dict()、to_json()、to_html()、stable_hash()、html_hash() 和 save()。

报告内容¶

所有 Profile（场景配置）都按同一实验生命周期组织：

阶段	展示证据
Design（设计）	程序类型和 hash、参数、测量、register snapshot/status、phase pattern、site-addressing 帧、程序结构、规范化 Problem 事实，以及适用时的显式罚项模型。
Validate（校验）	按阶段和严重级别分组的诊断，包括 control-constraint 检查、阻断错误和警告。
Plan（计划）	编译或模拟计划、control schedule、映射、Hamiltonian 项分配、所选方法、资源估算，以及适用时的带噪目标函数请求。
Execute（执行）	Backend、方法、设备、seed、steps、workers、耗时、内存证据、trace、选中的目标函数执行和源/runtime Program 溯源。
State / Noise（状态与噪声）	状态摘要和 hash、Hybrid 状态交接、运行时 register snapshot、addressing/phase-pattern consumer 和物理噪声记录。
Measure（测量）	shots、counts、probabilities、bit 或 occupation 编码、不确定性字段和最终采样噪声执行。
Analyze（分析）	observables、扫描趋势、解码后的 Problem 候选解、业务目标/罚项/总目标分解、实际目标值与历史最优值、可行率、约束违反、参数轨迹、有界经典基准差值、item 失败信息或对齐运行之间的差异。

源数据中不存在的事实会显示为 unavailable 并说明原因。Renderer（渲染器）不会推测硬件事实，也不会把路线图能力写成已实现能力。

原子排列、合并后的 Rabi / Detuning / Phase 波形图、测量分布和扫描趋势均使用交互式 Bokeh 图表，支持平移、缩放、重置、保存和 hover。Bokeh 是 CASCAQit 正式 runtime 依赖；每份独立报告只内嵌一次核心 BokehJS。Model-id 规范化保证相同报告内容的 html_hash() 稳定；重新模拟可能记录不同的 wall time 或 process RSS，因此报告内容与 hash 也可能变化。

报告场景¶

visualize() 会根据输入自动选择对应的报告 Profile：

输入	场景内容
Digital `ResultIR`	Circuit gates、qubit order、measurement registers、counts、probabilities 和 Z observables。
Analog `ResultIR`	原子排列与状态、active order、global/local control、addressing、phase pattern、control diagnostics、波形、occupation 和 probabilities。
Hybrid `ResultIR`	Digital/Analog block 顺序、mapping、register/control 证据、原子与波形视图、状态交接、noise trace 和末端测量。
Scan result	参数表、item 状态、counts、observable 趋势、失败信息和资源计划。
`ResultIR` mapping	输入对齐，以及 counts、probability、observable、method、noise 和 resource 差异。
Batch result	聚合状态、item/result references、部分失败和 diagnostics。
`SampledObjectiveEvaluationIR`	QWC 计划与基变换、分组 Job、raw counts、Pauli 能量贡献、考虑协方差的不确定性和最终能量。启用读出缓解后，还会显示校准标识与条件数、raw/mitigated 逐项贡献和分组统计、方差放大倍数及两组置信区间。
`VariationalResult`	Hamiltonian、ansatz、优化起点边界与终止信息、启用时的 SPSA 在线停止配置/窗口/逐项检查、objective history、最终中心目标、final counts、Problem candidate、baseline、gap 和 provenance。带噪运行还会显示请求的通道/options、实际 SimulationPlan、NoiseReport、estimator、不确定性、Backend Job/成本，以及独立的最终采样执行。
`VQEStabilityDiagnosticResult`	选中 start 的状态、诊断阈值、末端目标代理、更新与梯度模长、采样标准误与 repeats、optimizer termination、预算上限，以及明确的不声明最优和严格收敛。
`VQERepeatedLayerExperimentResult`	每个已保存的 VQE 层数/repeat 运行、原始目标值、Student-t 区间、配对改善下置信界、选层与停止证据、累计执行成本，以及选中 run 的完整 Algorithm 生命周期和 counts。
`ProblemExecutionResult`	规范化目标、逻辑 Hamiltonian、适用时的罚项充分性、Target 映射、Hamiltonian 项分配、参数模式、生成的原生程序、逐起点执行与 SPSA 停止证据、counts、解码候选解、期望与逐候选能量分解、目标历史、可行率、约束违反、参数轨迹和有界经典基准差值。带噪 Digital 运行同时保留源 Program 与 runtime Program 哈希，不隐藏物理噪声 wrapper。
`ProblemExecutionResult` mapping	同一个 Problem 的已完成运行，可对比层数、优化配置，或 Digital QAOA、Digital VQE、Hybrid QAOA、Analog QAA 路线。
`ProblemLayerExperimentResult`	已完成的连续层数执行，以及最小改善阈值、数值容差、patience、分层初值来源、逐层改善、当前选中层、最终选中层、停止原因和总求值次数。
`ProblemRepeatedLayerExperimentResult`	每个层数和 repeat 的完整优化、原始目标样本、均值与 Student-t 区间、配对改善及下置信界、选中层、停止原因和完整优化/求值成本。

Analog 和 Hybrid 的波形面板展示 duration、时间/数值单位及 global/local 控制范围。独立的寻址时间线列出每一帧、active site/weight、source kind 和 addressing hash；State 阶段显示 runtime 记录的实际数值 consumer。

常用方式¶

为单个结果保存包含设计上下文的报告：

visualize(result, program=program, output="experiment.html")

先检查结构化报告，再保存文件：

report = visualize(result)
measurement = report.section("experiment.measure")
report.save("experiment.html")

对比已经对齐的结果，不重复执行：

visualize(
    {"ideal": ideal_result, "noisy": noisy_result},
    output="comparison.html",
)

展示完成的参数扫描：

visualize(scan_job.result(), output="sweep.html")

展示已有 QAOA 或 VQE 结果，不重新运行 optimizer：

visualize(variational_result, output="algorithm.html")

固定参数 sampled VQE 也使用同一个调用。启用读出缓解后，先核对校准来源/hash 和条件数，再对照 raw 与 mitigated 的 Pauli 贡献，以及每个分组的方差放大倍数。counts 图仍展示 Backend 返回的原始整数证据；报告不会用 quasi probability 覆盖 counts，也不会重新测量。

展示已完成的 VQE 稳定性诊断，不增加 Backend 工作：

diagnostic.report("vqe-stability.html", language="zh")
# 等价的通用入口：
visualize(diagnostic, output="vqe-stability.html", language="zh")

展示已经执行完成的编译 Problem，不重新执行或重新编译：

visualize(problem_execution, output="problem.html", language="zh")
# 等价的便捷接口：
problem_execution.report("problem.html", language="zh")

展示已经完成的自动层数实验，不增加 optimizer 或 Backend 工作：

visualize(layer_experiment, output="problem-layer-experiment.html")
# 等价的便捷接口：
layer_experiment.report("problem-layer-experiment.html", language="zh")

有限 shots Digital VQE 报告把独立确认能量标为 Layer objective，并与末端计算基采样得到的 Problem objective 分开显示。成本区分别列出目标求值、候选确认和末端采样的 Job 与 shots；生成页面只读取已保存事实，不会增加执行。

从已保存的统计证据生成重复层数实验报告：

visualize(
    repeated_layer_experiment,
    output="problem-repeated-layer-experiment.html",
)
# 等价的便捷接口：
repeated_layer_experiment.report(
    "problem-repeated-layer-experiment.html",
    language="zh",
)

同样的调用也接受 standalone VQERepeatedLayerExperimentResult。报告使用 algorithm Profile，并以统计选中层内目标值最低的 run 展示详细生命周期。

多个执行完成后可以直接对比。下面是不同 QAOA 层数的例子：

visualize(
    {
        "p=1": result_p1,
        "p=2": result_p2,
        "p=3": result_p3,
    },
    output="qaoa-layers.html",
)

同一个 API 也接受不同路线：

visualize(
    {
        "Digital QAOA": digital_qaoa_result,
        "Digital VQE": digital_vqe_result,
        "Hybrid QAOA": hybrid_qaoa_result,
        "Analog QAA": analog_qaa_result,
    },
    output="problem-routes.html",
)

所有结果必须使用相同的 problem_hash 和逻辑变量顺序。模式、算法、Target、编译/程序标识、层数、优化预算和 shots 可以不同，报告会逐项保留。目标值与能量分解来自同一个规范 Problem，可以直接对齐；候选分布要结合 shots 和概率来源解读；收敛过程与本地资源只作证据展示，不自动排名。对比过程不会调用 Backend，也不会重新运行 optimizer。

可序列化的 ProblemExecutionContextIR 保存 analysis、适用时的罚项模型、Hamiltonian 项映射、参数模式，以及实际执行的 Digital、Analog 或 Hybrid 原生程序快照。因此，即使结果经过 JSON 往返，也不需要原编译器对象就能重建 Problem 报告。普通 QUBO/Ising 报告会把罚项分析标记为不适用，不会根据系数猜测罚项语义。

运行当前最完整的 3x3 原子阵列离线示例：

python3 examples/user/complete_physical_hybrid_demo.py \
  --output examples/user/assets/complete_physical_hybrid_report.html

该命令会分别保留 Hybrid、Comparison、理想 Sweep 和带噪 Sweep 报告。digital_workflow.py 与 analog_workflow.py 展示同一 API 在单模式结果上的用法。

如需重点检查 register preparation、Target control constraint 和逐 site phase，运行：

python3 examples/user/experiment_control_and_register.py \
  --output examples/user/assets/experiment_control_register_report.html

如需在同一个 3x3 MIS 上比较三种 Problem 编译模式，运行：

PYTHONPATH=src python3 examples/user/problem_compiler_3x3_mis.py \
  --output-dir artifacts/problem_compiler_3x3_mis \
  --language zh

脚本会保留 Digital、Hybrid、Analog 三份单路线报告和一份跨路线报告。每种模式都实际执行两个参数点；对比报告复用这些已完成结果，不会增加 Job。

如需查看带权结果和四条可执行路线，运行：

PYTHONPATH=src python3 examples/user/problem_compiler_mwis.py \
  --output-dir artifacts/problem_compiler_mwis \
  --language zh

MWIS 报告会增加节点权重表、每个候选解的已选总权重和完整结果分布的期望已选权重。对比报告使用同一个规范 Problem 已完成的 Digital QAOA、Digital VQE、Hybrid QAOA 和 Analog QAA 结果。

运行并保留自动 Hybrid QAOA 层数实验：

PYTHONPATH=src python3 examples/user/problem_layer_experiment.py \
  --output artifacts/problem_layer_experiment.html

脚本使用相同的单层 optimizer 预算实际执行 p=1 和 p=2。报告会说明 p=2 是否达到改善阈值、最终保留哪一层、为何停止，以及总共执行了多少次目标求值。

按独立优化重复比较层数：

PYTHONPATH=src python3 examples/user/problem_repeated_layer_experiment.py \
  --output artifacts/problem_repeated_layer_experiment.html

示例在 p=1 和 p=2 各执行两次完整 Digital QAOA 优化。报告展示全部 run、各层均值与 Student-t 区间、配对改善下置信界、选中层，以及四次优化对应的 Backend 总求值成本。

对通用 Pauli Hamiltonian 运行同样的统计选层流程：

PYTHONPATH=src python3 examples/user/vqe_repeated_layer_workflow.py \
  --output artifacts/vqe_repeated_layer_experiment.html \
  --language zh

报告保留四次 VQE 优化、置信证据、累计 Backend 成本和最终采样任务。选中 run 面板展示选中层内目标值最低的 repeat，不会丢弃其他 repeat，也不代表全局最优。

当前限制¶

当前只支持 HTML 报告，不支持 PNG 或 PDF 导出。
报告标准界面支持 English / 中文切换，Result 中的用户数据、ID、诊断原文和单位不会被翻译；报告不是实时更新的 dashboard。
Comparison 接收已经对齐的 ResultIR、同一个规范 Problem 的 ProblemExecutionResult、一个 ProblemLayerExperimentResult 或一个 ProblemRepeatedLayerExperimentResult。同一个 mapping 不能混用不同结果类型，也不能额外传入 program context。跨路线报告不会归一化不同优化预算、shots、主机负载或路线资源单位。
重复层数实验中的区间和配对下界只描述当前配置下已保存的独立优化结果，不证明全局最优、真机性能或量子优势。
Batch 当前展示聚合状态和结果引用；当 Batch 契约未携带子结果 payload 时，逐 item 测量内容会明确标记为 unavailable。
渲染只读取结构化 program/result metadata，不会执行 Job、访问网络、加载凭证或读取外部 artifact bytes。

SDK 1.0.8a · `8b227bff`