文档版本 dev

ParameterScan

from cascaqit import ParameterScan

ParameterScan

ParameterScan(
    scan_id: str,
    mode: ParameterScanMode,
    points: tuple[dict[str, ParameterScalar], ...],
    metadata: dict[str, Any] = dict(),
    schema_version: str = CANONICAL_PARAMETER_SCHEMA_VERSION,
)

定义一组有序参数点。推荐使用 explicit() 或 cartesian()；直接构造需给出 scan_id、mode 和 points。mode 为 explicit 或 cartesian，扫描值为有限的 bool、int 或 float，具体类型和边界由参数管理器进一步检查。metadata 与 schema_version 随声明保存。

expand() 只做参数绑定，不调用后端。实际执行使用 LocalBackend.run(program, sweep=scan, shots=...)，见参数扫描。

from cascaqit import Parameter, ParameterManager, ParameterScan

manager = ParameterManager().declare(Parameter("theta"))
scan = ParameterScan.explicit(scan_id="scan.theta", points=[{"theta": 0.0}, {"theta": 0.5}])
expanded = scan.expand(manager)
assert not expanded.has_errors
assert len(expanded.bind_sets) == 2
assert expanded.metadata["execution_performed"] is False

explicit

explicit(
    *,
    scan_id: str,
    points: tuple[dict[str, ParameterScalar], ...]
    | list[dict[str, ParameterScalar]],
    metadata: dict[str, Any] | None = None,
) -> ParameterScan

保留 points 的输入顺序，复制并规范化每个名称到标量的字典，返回扫描声明。非法标量或非字典点会报错。空列表可以构造，但 expand 会返回空扫描诊断。

cartesian

cartesian(
    *,
    scan_id: str,
    grid: dict[
        str,
        tuple[ParameterScalar, ...] | list[ParameterScalar],
    ],
    metadata: dict[str, Any] | None = None,
) -> ParameterScan

按参数名称排序各轴，再按各轴给出的值顺序展开笛卡尔积；最后一条轴变化最快。空 grid 或任何空轴得到零个点。它会立即生成全部点，大网格应先估算各轴长度乘积。

expand

expand(manager: ParameterManager) -> ParameterScanResult

通过 manager 逐点绑定，返回 ParameterScanResult。bind_sets 保存有效且不重复的点，diagnostics 记录失败点及 scan_index。按解析后的完整参数值判定重复，重复点不保留。结果可能同时含有效绑定与错误，先检查 has_errors 再决定是否执行，不能仅凭 bind_sets 非空判断整个扫描成功。

from_dict

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

从字典还原 ParameterScan。保留点顺序，重新检查模式与点值的基本格式。 缺少必需字段或字段不合法时可能抛出 KeyError、TypeError 或 ValueError。

from_json

from_json(text: str) -> ParameterScan

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