文档版本 dev

visualize

from cascaqit import visualize

visualize

visualize(
    source: object,
    *,
    program: ProgramContextSource | None = None,
    profile: ProfileSelection = "auto",
    output: OutputPath | None = None,
    title: str | None = None,
    language: Literal["en", "zh"] = "en",
) -> ExperimentReport

根据已有结果生成标准实验报告，返回 ExperimentReport。source 决定可用内容：单个 ResultIR、扫描或批次结果、变分优化结果、问题求解结果、分层实验、梯度、采样目标、VQE 稳定性诊断与采样基准都有对应入口。函数读取已存结果，不重新运行实验或优化。

profile="auto" 自动选择报告类型。可显式指定 digital、analog、hybrid、sweep、comparison、batch、algorithm 或 problem，但必须与 source 匹配。program 只允许用于单个 ResultIR，可补充对应程序的设计信息；不接受把一个程序上下文套在整组比较上。

比较报告使用 {标签: 结果} 映射，至少两个结果，且必须都为 ResultIR 或都为 ProblemExecutionResult；还会检查是否适合比较，例如问题身份与逻辑顺序。任意两份结果不能仅靠放入字典就成为有效对照。title 可覆盖标题，显式标题必须为非空字符串。

from cascaqit import Circuit, visualize

circuit = Circuit(1).h(0).measure_all()
result = circuit.run(shots=16, seed=7)
report = visualize(result, program=circuit)
assert report.profile == "digital"
html = report.to_html(language="zh")
assert 'id="report-language"' in html

传 output 时立即保存 HTML；路径必须以 .html 结尾，父目录必须已存在，已有同名文件会被覆盖。路径可为字符串或 PathLike。language 只接受 en 或 zh，默认 en，控制这次保存的初始语言。报告对象本身不记住语言；后续调用 report.to_html() 或 report.save() 时仍需显式传 language="zh"。

不支持的 source 类型会抛出 TypeError，语言、profile、标题或输出路径不合法通常抛出 ValueError，文件写入也可能产生系统错误。报告 HTML 支持正文与图表语言切换；API 标识、原始诊断和 JSON 保留原值。完整使用见标准实验报告。