build_counts_histogram¶
from cascaqit import build_counts_histogram
build_counts_histogram ¶
build_counts_histogram(
result: ResultIR,
*,
measurement_key: str | None = None,
visualization_id: str | None = None,
title: str = "Counts histogram",
) -> CountsHistogramVisualizationIR
从 ResultIR 提取直方图数据，返回 CountsHistogramVisualizationIR。它不会打开窗口、保存图片或重新采样；需要 HTML 报告时使用 visualize。
一个显式寄存器时可省略 measurement_key；多个寄存器必须指定它。没有显式测量记录时使用结果顶层 counts。错误 result 类型抛出 TypeError，多寄存器未指定 key 抛出 ValueError，未知 key 沿用 measurement() 的 KeyError。
返回的 bars 按位串排序，每项包含 bitstring、count 和 probability。这里 probability 是 count / result.shots 的记录频率；shots 为零时填 0，缺失位串不会自动补零。spec 保存标题、坐标和源结果哈希，metadata 保留所选测量及位序。visualization_id 可显式设置，默认由 result_id 派生。
from cascaqit import Circuit, build_counts_histogram
result = Circuit(1).x(0).measure_all().run(shots=16, seed=7)
histogram = build_counts_histogram(result)
assert histogram.bars[0]["bitstring"] == "1"
assert histogram.bars[0]["count"] == 16
assert histogram.bars[0]["probability"] == 1.0
绘图数据与物理概率的区别见执行记录。