HybridProgram¶
from cascaqit import HybridProgram
HybridProgram ¶
HybridProgram(
program_id: str,
syntax_hash: str = "0" * 64,
blocks: tuple[HybridProgramBlock, ...] = (),
dependencies: tuple[BlockDependency, ...] = (),
source_map: SourceMap = SourceMap(),
metadata: dict[str, Any] = dict(),
schema_version: str = ORCHESTRATION_SCHEMA_VERSION,
_payloads: Mapping[str, object] = dict(),
_hir: SemanticProgramHIR | None = None,
)
按顺序组合数字线路、模拟演化与终端测量。通常从 HybridProgram(program_id="experiment") 开始，再调用 digital()、analog() 和 measure_all()。这些方法返回新程序，必须接住返回值；传入的载荷会保存快照，之后修改原始 Circuit 不会更新已加入的块。
直接构造时，blocks、dependencies、source_map、syntax_hash、metadata 与 schema_version 描述编排信息。它们供高级编译工作流使用；不要自行填写私有参数 _payloads 与 _hir。块名用于阅读，同名块可以出现多次；定位某次调用时使用唯一 block_id。
下面只使用数字块，也经过相同的 Hybrid 提交路径。块内部不放终端测量，由 Hybrid 程序统一测量。
from cascaqit import Circuit, HybridProgram
original = HybridProgram(program_id="hybrid_x")
program = original.digital("flip", Circuit(1).x(0)).measure_all()
assert original.blocks == ()
assert program.run(shots=32, seed=7).result().counts == {"1": 32}
restored = HybridProgram.from_ir(program.to_ir())
assert restored.run(shots=32, seed=7).result().counts == {"1": 32}
保存时区分两种用途：to_dict()/to_json() 保存编排声明，不保存执行载荷；to_ir() 导出已绑定的程序及其载荷，可用 from_ir() 恢复执行。概念与实验见共享参数。
digital ¶
digital(
name: str,
circuit: Circuit | DigitalProgramIR,
*,
mapping: Mapping[str, str] | None = None,
) -> HybridProgram
追加 Circuit 或 DigitalProgramIR 的快照，返回新 HybridProgram。name 为块名，mapping 将载荷逻辑 ID 映射到目标 ID，未指定项保持同名映射；未知逻辑 ID 会报错。不能在终端测量之后追加块。
analog ¶
analog(
name: str,
program: AHSProgram | ProgramIR,
*,
mapping: Mapping[str, str] | None = None,
) -> HybridProgram
追加 AHSProgram 或 ProgramIR 的快照，返回新 HybridProgram。mapping 与 digital() 使用相同规则；跨块逻辑顺序与映射仍需通过编译和执行检查。用于 Hybrid 的 AHSProgram 不需自行声明终端测量。
为已有逻辑 ID 添加一个计算基终端测量，返回新程序。name 是块名，key 是结果中的测量键。空程序或已有测量时抛出 ValueError；当前只支持一次终端测量。
从已附加的 Circuit/AHSProgram 载荷收集参数，返回 ParameterManager，包含参数到块的映射。同名且相同的声明共享绑定；同名但类型、单位、默认值等声明不一致时抛出 ValueError。
按参数名绑定并投射到各载荷，返回新程序。缺值、未知名称或范围错误由参数管理器检查，失败时抛出 ProgramValidationError，错误元数据保留参数诊断。
按 block_id 或唯一块名给已有块附加载荷快照，返回新程序。载荷类型必须匹配数字或模拟块；重名时需使用 ID。它也会更新参数声明和载荷摘要，适合给 from_hir() 得到的编排补充可执行内容。
按 ID 或唯一块名返回载荷快照，不返回内部可变对象。未知名称、重名或块没有载荷时抛出 ValueError；测量块没有数字/模拟载荷。
返回 HybridAnalysisResult，含程序摘要、参数 schema 摘要、validate() 诊断和保留的 HIR。普通 Python 构建程序的 hir 可以是 None。此步骤不执行载荷。
返回编排诊断元组，检查块、依赖、映射连续性与测量生命周期。空诊断只表示这些编排检查未发现问题，不能替代载荷绑定、目标检查和执行预检。
返回 HybridCompileResult，包含图、非可执行的本地计划与诊断；错误时 plan 可能为 None。allowed_capabilities 可限制允许的能力。编译计划本身不能传给 LocalBackend.run() 执行。
execution_builder ¶
execution_builder(
*,
params: Mapping[str, bool | int | float] | None = None,
shots: int = 1000,
seed: int = 0,
measurement_key: str | None = None,
parameterized: bool = False,
) -> LocalHybridExecutionBuilder
编译并把已有载荷附加到 LocalHybridExecutionBuilder。普通模式使用 params 或默认值绑定；parameterized=True 保留参数工厂供扫描使用，不能同时传 params。shots、seed 和 measurement_key 配置测量。编译失败或缺载荷抛出 ProgramValidationError。返回 builder 尚未执行。
prepare ¶
prepare(
*,
params: Mapping[str, bool | int | float] | None = None,
shots: int = 1000,
seed: int = 0,
measurement_key: str | None = None,
bundle_id: str | None = None,
) -> LocalExecutionBundleResult
调用 execution_builder().build()，返回 LocalExecutionBundleResult；检查 bundle 是否存在以及 diagnostics。bundle_id 可指定包标识。此步骤组装一次已绑定执行，不采样，也不返回 ResultIR。
run ¶
run(
*,
backend: object | None = None,
params: Mapping[str, bool | int | float] | None = None,
sweep: ParameterScan | None = None,
noise: object | None = None,
options: SimulationOptions | None = None,
shots: int = 1000,
seed: int | None = None,
optimization_level: int = 0,
) -> object
调用 backend.run() 并返回任务，使用 job.result() 取得结果。未提供 backend 时创建 LocalBackend。params、sweep、noise、options、shots 与 seed 交给后端处理。optimization_level 支持 0 与 1；1 先绑定再简化程序，并保存优化说明，当前不能与 sweep 合用。
按当前程序顺序返回具有该块名的调用 ID 元组。没有匹配时返回空元组。
将唯一块名解析为调用 ID。找不到或同名调用超过一次时抛出 ValueError；重复调用请用 block_ids() 后选择明确的 ID。
插入一个 cascaqit.hybrid.HybridProgramBlock，返回新程序。index=None 追加，其他索引须在 0 到当前块数之间。此高级入口添加编排块，不自动附加执行载荷；需要时再调用 with_payload()。
按 ID 删除块、涉及它的依赖及其载荷，返回新程序。未知 ID 抛出 ValueError。删除后仍需重新检查测量与逻辑映射。
在当前程序后追加另一个 HybridProgram 的块与依赖，合并载荷和来源信息，返回新程序。它不自动重命名冲突的 block_id，也不修复测量顺序；组合后需 validate()/compile()。
将给定 block_id 移到从 0 开始的 new_index，返回新程序。索引须小于块数；越界抛出 IndexError，未知 ID 抛出 ValueError。不会同步改写显式依赖。
用所有现有块 ID 的精确排列设置顺序，返回新程序。不能遗漏、重复或添加 ID。显式依赖仍需与新顺序一致，否则后续检查会报错。
追加一个 cascaqit.hybrid.BlockDependency，返回新程序。仅添加声明，端点、环与顺序约束在后续 validate()/compile() 中检查。
从已完成语义分析的 SemanticProgramHIR 建立编排块并保留 HIR。类型错误或引用未知声明会报错。该转换不自带执行载荷，需要 with_payload() 补充。
返回含载荷的已绑定 HybridProgramIR。缺载荷、未绑定参数、块内嵌终端测量或不支持的载荷类型会报错。导出编排声明请用 to_dict()；保存可恢复执行的程序请使用这里的 IR。
从 HybridProgramIR 恢复带载荷的 HybridProgram，重建数字、模拟与测量块，保留块 ID、映射和元数据。测量块需要一个测量条目；其他输入类型抛出 TypeError。
返回编排声明字典，含块、依赖、来源与元数据；明确排除私有载荷和 HIR。仅凭此字典恢复的程序不能直接继续执行，需重新附加载荷。
将 to_dict() 的编排声明编码为 JSON 字符串，indent 控制缩进，不写文件，也不保存执行载荷。
返回编排声明规范 JSON 的 SHA-256 摘要。附加载荷时记录在块元数据中的 payload_hash 会参与摘要，但完整私有载荷不直接序列化。它不是两个程序物理等价的判据。
从字典还原 HybridProgram。只还原编排字段，不还原执行载荷或 HIR。 缺少必需字段或字段不合法时可能抛出 KeyError、TypeError 或 ValueError。
解析 JSON 对象并调用 from_dict()，返回 HybridProgram。非法 JSON 会抛出解析错误；顶层不是对象时抛出 TypeError。