Circuit¶
from cascaqit import Circuit
Circuit ¶
Circuit(
qubits: int | Sequence[str],
*,
program_id: str = "program.digital",
metadata: dict[str, Any] | None = None,
)
构造静态数字线路，并可在本地执行。qubits 可为正整数，生成 q0、q1 等名称，也可为显式的唯一名称序列。program_id 标识线路，metadata 保存用户信息。逻辑顺序由构造时的 qubits 决定，测量位串顺序则由测量目标顺序决定。
门方法、append()、compose() 和测量方法修改当前线路并返回它。bind()、snapshot()、inverse()、repeat() 和 controlled() 返回独立线路。旋转角用 rad；被引用的符号参数必须先绑定，默认值也通过显式 bind() 应用。
见Bell 态实验和数字线路详解。这里的执行入口用于本地模拟，不提交真机任务。
常用操作与执行¶
append ¶
append(
operation: str | OperationBinding | DigitalOperationIR,
qubits: QubitRef | Sequence[QubitRef] | None = None,
*,
parameters: Mapping[str, DigitalValue] | None = None,
) -> Circuit
追加目录中已定义的操作，可传操作名、OperationBinding 或 DigitalOperationIR。名称形式用 qubits 与 parameters 提供目标和参数；绑定对象已有参数，不能再次覆盖；完整 IR 不能覆盖目标或参数。无效操作、目标或参数会抛出 ProgramValidationError。
compose ¶
compose(
other: Circuit,
*,
qubit_map: Mapping[QubitRef, QubitRef] | None = None,
) -> Circuit
把 other 追加到当前线路。qubit_map 将子线路全部量子位映射到当前线路，缺省映射也必须可解析。同名参数的默认值和边界需一致，测量 key 不得冲突。当前线路已测量后不能继续追加操作。
parameter ¶
parameter(
name: str,
*,
default: float | None = None,
lower_bound: float | None = None,
upper_bound: float | None = None,
) -> Parameter
声明本线路拥有的浮点弧度参数，返回 Parameter。可设置默认值和上下界。重复名称、非有限默认值或非法边界会抛出 ProgramValidationError。
按名称绑定 values，返回独立线路。被引用但未提供的参数使用默认值，没有默认值则报错。未知名称、非有限值和越界值会抛出 ProgramValidationError。绑定后的原始参数声明仍可检查。
以计算基测量指定量子位，可只选部分或调整顺序。key 缺省生成 m0、m1 等，显式 key 必须非空且唯一。返回当前线路；此后不能添加量子门。多个测量寄存器的结果应通过 result.measurement(key) 分别读取。
按线路量子位顺序测量全部量子位，默认 key 为 m。它等价于以全部 qubits 调用 measure()。
run ¶
run(
*,
shots: int = 1000,
seed: int | None = None,
return_probabilities: bool = False,
optimization_level: int = 0,
) -> ResultIR
返回本地模拟的 ResultIR。shots 为采样次数，seed 控制随机采样；要读取精确状态概率，显式传 return_probabilities=True，此处默认为 False。optimization_level 支持 0 或保持语义的化简级别 1。未绑定参数、非法程序或执行配置会导致失败；需要噪声和任务历史时使用 LocalBackend。
返回 DiagnosticsIR 元组。未绑定线路返回错误诊断，而不是执行模拟。检查诊断的 severity；不要把非空元组一律解释为失败或成功。
要求参数已绑定，返回规范的 DigitalProgramIR。导出不会执行线路；未绑定时抛出 ProgramValidationError。
与 to_program() 等价，返回 DigitalProgramIR。
复制线路声明、操作和来源记录，返回可独立修改的线路。
返回操作逆序并逐个取逆的新线路。只支持可求逆的幺正操作；已含测量的线路会抛出 ProgramValidationError。
返回重复 count 次的新线路。count 必须是 1–1024 的整数，布尔值无效。含测量线路只允许重复一次；无效次数或重复测量会抛出 ProgramValidationError。
返回增加 new_control 的受控线路；新控制位排在原逻辑顺序前面。名称必须非空且不能已存在，线路不能含测量。可受控的操作受目录能力限制，不保证任意线路都能加控制。
返回程序标识字符串。
返回逻辑量子位名称元组，顺序与构造时一致。
返回用户信息和变换信息的深拷贝。修改返回字典不会修改线路元数据。
按源代码顺序返回规范操作视图。参数声明仍可保留在未绑定线路内；数值执行前仍须绑定。
按操作顺序返回名称元组，包含已声明测量的操作。
按声明顺序返回 Parameter 元组。
返回操作实际引用的参数名称，去重并排序。它可能少于已声明参数。
返回线路能否降为纯数值操作。仅有默认值的符号引用仍需显式绑定。
返回 ProgramSourceMapIR，用于将操作关联到其声明来源。此方法先导出数值程序，因此要求参数已绑定；查看未绑定声明的来源可用 source_evidence()。
返回按当前操作顺序排列的来源记录元组。
返回可序列化的线路结构字典，包含参数声明、操作和经典寄存器，可供 from_structural_payload() 还原。
返回线路结构的稳定哈希，供比较来源和变换使用。哈希相同不是两个物理实验结果相同的证明。
from_structural_payload ¶
from_structural_payload(
payload: Mapping[str, Any],
*,
program_id: str = "program.digital.restored",
) -> Circuit
从结构字典还原线路，保留可绑定声明。输入须符合该序列化结构，损坏或不支持的内容会报错。
逐个返回操作参数出现位置及其 ID、源结构哈希、仿射形式和支持情况。相同参数出现在不同门中会有不同位置，适合按门分析梯度。
shift_parameter_occurrence ¶
shift_parameter_occurrence(
occurrence_id: str, shift: float
) -> Circuit
按当前快照提供的 occurrence ID，只移动一个符号 RX/RY/RZ 的 theta，返回新线路。shift 为有限弧度值；未知 ID、纯数值参数或其他门会抛出 ProgramValidationError。
门方法¶
这些方法返回当前线路。量子位可用从零开始的索引或已声明名称；多比特门目标必须互不相同。越界、未知名称、非法门参数或测量后加门会抛出 ProgramValidationError。
追加恒等门。
追加 Pauli X 门，交换计算基态。
追加 Pauli Y 门。
追加 Pauli Z 门，使 1 态分量变号。
追加 Hadamard 门。
追加相位门 diag(1, i)。
追加 S 的逆门 diag(1, -i)。
追加相位门 diag(1, exp(iπ/4))。
追加 T 的逆门。
追加绕 X 轴旋转，theta 用弧度，可为参数或表达式。
追加绕 Y 轴旋转，theta 用弧度，可为参数或表达式。
追加绕 Z 轴旋转，theta 用弧度，可为参数或表达式。
追加相位门 diag(1, exp(i theta))，theta 用弧度。
追加三角度单比特 U 门，theta、phi、lam 均用弧度，参数次序见签名。
追加受控 X，control 为控制位，target 为目标位。
追加受控 Y。
追加受控 Z。
交换 left 与 right 两个不同量子位。
追加双控制 X 门，两个控制位与目标位必须各不相同。