文档版本

Observable¶

from cascaqit import Observable

Observable ¶

Observable(
    name: str,
    terms: tuple[PauliTerm, ...],
    schema_version: str = OBSERVABLE_SCHEMA_VERSION,
)

声明一个有名称的 Pauli 乘积。terms 包含作用于不同逻辑目标的 PauliTerm，每个项的基为 I、X、Y 或 Z。项必须非空，目标不能重复；name 必须是无首尾空白的非空字符串。

一个 Observable 表示算符乘积，不表示多个项的加权和。需要哈密顿量之和时使用 PauliHamiltonian。简单观测量通常通过 PauliX()、PauliZ() 或 PauliProduct 创建；直接构造所需的 PauliTerm 位于 cascaqit.observables。

声明不执行测量，也不会自动给线路追加旋转门。把多个声明放入 ObservableSet 并传给支持的后端；结果应结合 estimator_kind 阅读。由精确态算出的 X/Y 期望不能称为从计算基计数估出的结果。见批量观测量。

from cascaqit import Observable, PauliProduct

xx = PauliProduct((("q0", "X"), ("q1", "X")), name="XX")
assert xx.targets == ("q0", "q1")
assert Observable.from_json(xx.to_json()) == xx

targets ¶

targets: tuple[str, ...]

按项的声明顺序返回目标名称元组，不自动排序。目标是否存在于所求值的状态中由求值器检查。

bases ¶

bases: tuple[PauliBasis, ...]

按同一顺序返回 PauliBasis 枚举元组，与 targets 逐项对应。

from_dict ¶

from_dict(data: Mapping[str, Any]) -> Observable

从字典还原 Observable。重建 terms 中的 PauliTerm 并重新检查空项、基和重复目标。缺少必需字段或字段不合法时可能抛出 KeyError、TypeError 或 ValueError。

from_json ¶

from_json(text: str) -> Observable

解析 JSON 对象并调用 from_dict()，返回 Observable。非法 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 十六进制摘要。字段、标识或元数据变化都可能改变摘要；它用于比较保存内容，不判断两个声明在物理上是否等价。