程序层（L5）

qaiji.core.program 描述有序的量子调用、实验元数据和结果输出。 调用通过固定配方生成的 kernel_ref 引用 L4 电路；校验时由调用方提供解析表， 逐个重算引用，并核对输出寄存器的唯一声明与每位测量写入。 判决针对调用时刻的解析表内容，电路随后发生变化时需要重新校验。

calibration_set_ref 与 device_profile_ref 是不透明引用，只保存和透传， 不读取其指向内容、不检查存在性，也不改变校验判决。本层不执行采样、调度或反馈。 从 OpenQASM 电路到程序校验的完整示例见 L5 程序引用与校验； 按调用关联原生调度测量事件见 显式配置的原生调度。

JSON 契约

ProgramIR 采用冻结数据类，序列保存为元组；输出顺序与重复调用均保留。 写端使用固定格式字段、键排序、紧凑分隔符与 ASCII 转义；读端接受非规范空白 和键顺序，但拒绝未知或缺失字段、任意层重复键、错误类型与不合法构造值。 格式版本不匹配会抛出 ValueError。Python 子类的额外字段不属于持久化身份。 JSON 往返只承载程序描述，L4 解析表由调用方另行提供。

模型与版本

qaiji.core.program.PROGRAM_SCHEMA_VERSION = 'qaiji.program.v0'

str(object='') -> str str(bytes_or_buffer[, encoding[, errors]]) -> str

Create a new string object from the given object. If encoding or errors is specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler. Otherwise, returns the result of object.__str__() (if defined) or repr(object). encoding defaults to 'utf-8'. errors defaults to 'strict'.

class qaiji.core.program.QuantumInvocation(kernel_ref)

一次量子内核调用。

示例

>>> QuantumInvocation("sha256:" + "a" * 64).kernel_ref.startswith("sha256:")
True

参数:

kernel_ref (str)

class qaiji.core.program.ExperimentMetadata(shot_count, calibration_set_ref=None, device_profile_ref=None)

实验参数及透传的不透明字符串引用，本仓不校验引用内容。

示例

>>> ExperimentMetadata(100).shot_count
100

参数:

• shot_count (int)

• calibration_set_ref (str | None)

• device_profile_ref (str | None)

class qaiji.core.program.ResultOutput(invocation_index, register_name)

一次调用的经典寄存器输出。

示例

>>> ResultOutput(0, "c").register_name
'c'

参数:

• invocation_index (int)

• register_name (str)

class qaiji.core.program.ProgramIR(*, schema_version='qaiji.program.v0', quantum_invocations, experiment_metadata, result_outputs)

以调用、实验参数及结果输出表达的 L5 程序。

示例

>>> program = ProgramIR(
...     quantum_invocations=[QuantumInvocation("sha256:" + "a" * 64)],
...     experiment_metadata=ExperimentMetadata(100),
...     result_outputs=[ResultOutput(0, "c")],
... )
>>> program.schema_version
'qaiji.program.v0'

参数:

• schema_version (str)

• quantum_invocations (tuple[QuantumInvocation, ...])

• experiment_metadata (ExperimentMetadata)

• result_outputs (tuple[ResultOutput, ...])

to_json()

写出键序固定、纯 ASCII 且无额外空白的规范 JSON。

返回:

包含每层全部字段的 JSON 文本，序列顺序保持不变。

抛出:

ValueError -- 超大整数超过标准库的整数转字符串位数限制。

返回类型:

str

classmethod from_json(text)

解析任意空白与键序的 JSON，逐层检查对象、键集和数组。

参数:

text (str) -- 程序 JSON 文本。

返回:

通过构造期校验的不可变程序。

抛出:

• ValueError -- 畸形 JSON 文本仅抛此异常族，含解析错误和嵌套过深。

• TypeError -- 不支持的非文本实参由标准库 json.loads 拒收。

返回类型:

ProgramIR

引用与校验

问题按调用序、再按输出声明序汇总；未通过引用认证的调用不再检查输出。 未被引用的表项不参与校验，被测量写入但未声明为结果输出的寄存器合法。 寄存器按名字解析；损坏电路触发的 L4 TypeError 原样传播。

qaiji.core.program.compute_kernel_ref(circuit)

用单参数固定配方计算引用，不 canonicalize，绑定 qaiji.semantic_summary.v0。

参数:

circuit (Circuit) -- 待计算引用的 L4 电路。

返回:

带 sha256 前缀的摘要哈希引用。

返回类型:

str

qaiji.core.program.validate_program(program, kernels)

认证调用并核对输出，按调用序、再输出声明序收集问题。

认证的是解析表内容，而非调用方持有的对象；未被引用的表项不校验。 被写入但未声明为输出合法，输出按寄存器名解析，继承 L4 的按名语义。 判决是调用时刻快照，之后修改电路不影响已经返回的结果。 损坏电路的 TypeError 原样传播，不转为程序问题。

参数:

• program (ProgramIR) -- 待校验的程序。

• kernels (Mapping[str, Circuit]) -- 引用到 L4 电路的解析表。

抛出:

• ProgramValidationError -- 引用认证或输出寄存器校验失败。

• TypeError -- L4 无法分类损坏电路中的节点。

返回类型:

None

专属异常

该异常定义在程序子包，继承 qaiji.QaijiIRError，从 qaiji.core.program 导入；包根、qaiji.core 与 qaiji.exceptions 不导出它。problems 为按报告顺序排列的不可修改字符串元组。

class qaiji.core.program.ProgramValidationError(problems)

基类：QaijiIRError

携带按判决顺序收集的全部程序问题。

参数:

problems (tuple[str, ...])