ReadoutCalibration¶
from cascaqit import ReadoutCalibration
ReadoutCalibration ¶
ReadoutCalibration(
calibration_id: str,
calibration_hash: str,
logical_order: tuple[str, ...],
matrices: tuple[ReadoutCalibrationMatrixIR, ...],
source: str,
metadata: Mapping[str, Any] = dict(),
schema_version: str = READOUT_MITIGATION_SCHEMA_VERSION,
)
保存逐比特的读出响应矩阵和来源信息。常用入口是 from_probabilities()，它从已知或已估计的错误率生成校准 ID 与摘要。这个调用不会测量设备，也不会从 NoiseModel 自动推断校准。
p01 表示制备 0 后测得 1 的概率，p10 表示制备 1 后测得 0 的概率。矩阵按“行是测得状态、列是真实状态”排列：A = [[1-p01, p10], [p01, 1-p10]]，因此观测概率 q = A @ p。逐比特模型假设读出响应可写成这些矩阵的张量积，不能描述任意相关读出误差。
logical_order 必须非空且唯一，matrices 必须按相同顺序覆盖每个逻辑比特。source 记录来源，例如独立校准实验或明确标注的模拟输入；metadata 可保存条件和时间。直接构造时，calibration_hash 必须与内容一致，calibration_id 必须为 readout.calibration.<摘要前20位>。通常不应自行拼写它们。
from cascaqit import ReadoutCalibration
calibration = ReadoutCalibration.from_probabilities(
logical_order=("q0", "q1"), p01={"q0": 0.1, "q1": 0.2},
p10=0.05, source="teaching_simulation",
)
matrix = calibration.matrix_for("q0")
assert matrix.response_matrix == ((0.9, 0.05), (0.1, 0.95))
assert calibration.total_condition_number >= 1.0
assert ReadoutCalibration.from_json(calibration.to_json()) == calibration
能成功保存校准不代表矩阵适合求逆；ReadoutMitigationConfig 会进一步拒绝奇异或条件数过大的输入。
from_probabilities ¶
from_probabilities(
*,
logical_order: Sequence[str],
p01: ProbabilityInput,
p10: ProbabilityInput | None = None,
source: str,
metadata: Mapping[str, Any] | None = None,
) -> ReadoutCalibration
从统一错误率标量或逐比特映射返回 ReadoutCalibration。概率必须有限且在 [0, 1] 内；映射键必须精确覆盖 logical_order。省略 p10 时采用与 p01 相同的对称错误率。source 为必需非空来源，内容、顺序、来源和元数据都参与生成校准摘要。
返回指定逻辑比特的 ReadoutCalibrationMatrixIR，可读取 response_matrix、determinant 与 condition_number。未知 target 抛出 KeyError。
返回只读映射，键为逻辑比特，值为其响应矩阵的 2-范数条件数。奇异矩阵可能返回无穷大；读取该属性不会修复矩阵。
返回所有逐比特条件数的乘积，即张量积响应矩阵的 2-范数条件数，无需构造指数大小的完整矩阵。比特数增加时，整体条件数可能远大于任一单比特条件数。
从字典还原 ReadoutCalibration。还原矩阵与来源，并重新核对 calibration_hash 和 calibration_id；修改保存字段后沿用旧摘要会报错。 缺少必需字段或字段不合法时可能抛出 KeyError、TypeError 或 ValueError。
解析 JSON 对象并调用 from_dict()，返回 ReadoutCalibration。非法 JSON 会抛出解析错误；顶层不是对象时抛出 TypeError。
返回可写入 JSON 的字典，嵌套对象一并序列化。元组转成数组；这个字典是保存的声明，不是执行结果。
返回 JSON 字符串，不写文件。indent=None 使用紧凑格式；提供缩进宽度可便于阅读。
返回规范 JSON 的 SHA-256 十六进制摘要。字段、标识或元数据变化都可能改变摘要；它用于比较保存内容，不判断两个声明在物理上是否等价。