文档版本 dev

NoiseModel

from cascaqit import NoiseModel

NoiseModel

NoiseModel(
    noise_model_id: str,
    channels: tuple[NoiseChannel, ...],
    metadata: dict[str, Any] = dict(),
    schema_version: str = "cascaqit.noise.physical.v1",
)

组合一组噪声通道，供 LocalBackend.run(..., noise=model) 使用。noise_model_id 不能为空，channels 至少包含一个 NoiseChannel。通道 ID 必须唯一，当前每种 channel_type 也只能出现一次；不能用两个同类型通道分别指定不同站点的不同速率。metadata 和 schema_version 随配置保存。

from cascaqit import NoiseChannel, NoiseModel

noise = NoiseModel("readout-only", channels=(NoiseChannel.readout(0.02, p10=0.04),))
assert noise.channel("readout").parameters["p10"] == 0.04
assert noise.channel("dephasing") is None
assert not noise.requires_trajectory
noise.validate_for(("q0",), has_digital=True, has_analog=False, is_hybrid=False)

执行方法、轨迹数、积分步数和 shots 由后端配置，不能只凭这个模型判断误差。含噪执行的状态、计数和成本解释见含噪 Hybrid 项目。

channel

channel(
    channel_type: NoiseChannelType,
) -> NoiseChannel | None

按 channel_type 查找通道，存在时返回 NoiseChannel，不存在时返回 None。查找不执行模拟。

requires_trajectory

requires_trajectory: bool

模型包含 atom_loss 通道时返回 True。False 不意味着无需数值规划，也不等于使用理想态矢量；其他物理噪声仍可能需要密度矩阵或轨迹。

validate_for

validate_for(
    logical_order: tuple[str, ...],
    *,
    has_digital: bool,
    has_analog: bool,
    is_hybrid: bool,
) -> None

根据 logical_order 检查目标，并根据三个布尔参数检查程序包含所需的 Digital、Analog 或 Hybrid 结构。成功返回 None；未知目标抛出 ProgramValidationError，缺少执行前提抛出 CapabilityError。此方法不验证具体控制调度；后端仍会检查实际程序与执行方法。

from_dict

from_dict(data: dict[str, Any]) -> NoiseModel

从字典还原 NoiseModel。逐项还原 channels 并重新检查 ID 与通道类型的唯一性。 缺少必需字段或字段不合法时可能抛出 KeyError、TypeError 或 ValueError。

from_json

from_json(text: str) -> NoiseModel

解析 JSON 对象并调用 from_dict()，返回 NoiseModel。非法 JSON 会抛出解析错误；顶层不是对象时抛出 TypeError。

to_dict

to_dict() -> dict[str, Any]

返回可写入 JSON 的字典，嵌套对象一并序列化。元组转成数组；这个字典是保存的声明，不是执行结果。

to_json

to_json(*, indent: int | None = None) -> str

返回 JSON 字符串，不写文件。indent=None 使用紧凑格式；提供缩进宽度可便于阅读。

stable_hash

stable_hash() -> str

返回规范 JSON 的 SHA-256 十六进制摘要。字段、标识或元数据变化都可能改变摘要；它用于比较保存内容，不判断两个声明在物理上是否等价。