Digital Circuit 使用指南¶
Circuit 是常用的 Digital 编程入口，支持静态 gate、Catalog 类型化参数、子线路复用、有边界的线路变换、终端测量和本地执行。DigitalOperationIR.arguments 保留规范的 bool、int 和有限 float，不会把所有参数都转为 float。
先运行 Bell 线路示例：
python3 examples/learning/digital_first_run.py
完整的线路接口示例位于 examples/user/digital_circuit_ergonomics.py。
声明参数¶
from cascaqit import Circuit
rotation = Circuit(("data",))
theta = rotation.parameter(
"theta",
lower_bound=-1.0,
upper_bound=1.0,
)
rotation.rx(theta, "data")
参数归声明它的 Circuit 所有。表达式支持常量、符号、+、-、*、/、** 和一元正负号；函数调用、属性访问、索引、复数和非有限结果会在绑定前被拒绝。
复用与变换¶
declaration = Circuit(("data",))
declaration.compose(rotation)
declaration.compose(rotation.inverse())
repeated = declaration.repeat(2)
append() 为当前 19 个受支持 gate 提供统一入口。compose() 可以使用相同 qubit layout，也可以传入完整 qubit_map；相同参数声明会合并，冲突则在目标线路变化前报错。
inverse() 只接受不含测量的线路。repeat(count) 的范围是 1..1024，已测量线路只能使用 repeat(1)。这些方法都返回独立线路，不修改原对象。
绑定与运行¶
bound = repeated.bind({"theta": 0.3})
result = bound.run(shots=0, return_probabilities=True)
bind() 返回新的 fully bound Circuit。参数缺失、名称未知、数值越界、非有限值或表达式计算失败都会产生结构化 ProgramValidationError。未完全绑定的线路不能调用 to_program() 或 run()，也不能作为 Local Hybrid 的 Digital payload。
未绑定 Circuit 仍可在不 lowering、不执行的情况下查看。Source visualization 读取只用于展示的声明期 evidence，Canonical visualization 则以结构化文本显示符号参数：
from cascaqit.visualization import build_circuit_visualization
source_view = build_circuit_visualization(rotation, stage="source")
assert source_view.nodes[0].label == "RX(theta)"
assert source_view.metadata["source_evidence_scope"] == "circuit_declaration"
source_map() 仍须等待参数绑定完成，因为 ProgramSourceMapIR 必须引用真实的 Program semantic hash。
绑定后，angle 和 float 参数会成为有限 float；Catalog 的结构参数保留精确类型：
assert isinstance(
bound.to_program().circuit.operations[0].arguments["theta"],
float,
)
from cascaqit.digital import std
qft = Circuit(3).append(std.qft(3, True, 0), (0, 1, 2)).to_program()
arguments = qft.circuit.operations[0].arguments
assert type(arguments["num_qubits"]) is int
assert type(arguments["do_swaps"]) is bool
assert type(arguments["approximation_degree"]) is int
添加控制 qubit¶
线路级 controlled transformation 支持 fluent Circuit API 中全部静态幺正门，包括参数化旋转、H、U、SWAP 和 nested control：
source = Circuit(("target",))
theta = source.parameter("theta")
source.h("target").rx(theta, "target")
controlled = source.controlled("control")
nested = controlled.controlled("outer").bind({"theta": 0.25})
每次新增的 control qubit 排在第一位。规范化的 operations 视图把结果表示为原 base definition 加 control modifier，不需要为每种受控门增加名字。嵌套 positive/negative control 会按有序 control operand 保留每一位 control_state，因此在已有 negative control 外增加 positive control 得到 10，不是 11。包含 terminal measurement 的线路会原子性拒绝。本接口可表示并在本地模拟内置 Circuit 门集的受控形式，但不会执行任意矩阵综合、分配 ancilla，也不证明硬件 Target 能执行该结果。
查看 Operation 与 facade¶
版本化 Operation 模型归 cascaqit.digital 所有。Fluent Circuit 和 std 都是可执行入口，operations 则提供规范化的 Definition/Application 视图：
from cascaqit.digital import standard_catalog, std
catalog = standard_catalog()
crx = std.rx(0.25).control().on("control", "target")
toffoli = std.toffoli().on("c0", "c1", "target")
assert catalog.resolve(crx.definition).semantic_kind == "unitary"
assert crx.definition == std.rx.key
assert crx.modifiers[0].control_count == 1
assert toffoli.definition == std.x.key
assert toffoli.modifiers[0].control_count == 2
Canonical Core 还定义了 rphi、xy、rxx、ryy、rzz、rzx、reset、barrier、delay，以及版本化的 QFT、H-layer 和 GHZ-preparation Composite contract。三个内置 Composite 已有 Simulator 和 Compiler 共用的确定性 semantic normalization，包括 exact/approximate policy、quota、cycle 和 GHZ input-contract 检查。通用用户自定义 Composite factory/template 解释器与自动 Target decomposition selection 仍未实现。
Facade 拼写是非语义的展示证据。Circuit 独立保存声明期 evidence，并在绑定后将其投影为 ProgramSourceMapIR：
import math
s_circuit = Circuit(1, program_id="same").s(0)
p_circuit = Circuit(1, program_id="same").p(math.pi / 2, 0)
assert s_circuit.to_program().stable_hash() == p_circuit.to_program().stable_hash()
assert s_circuit.source_map().stable_hash() != p_circuit.source_map().stable_hash()
构建 Source 视图时可直接传入 Circuit，或在传入 DigitalProgramIR 时同时传入 source_map=circuit.source_map()。裸 Program 没有 facade evidence，因此会回退到 Canonical label，并设置 source_label_status="unavailable"。Source Map 不影响优化、编译、Target matching、执行或 Program hash。
运行 digital_operation_catalog.py 并传入 --output artifacts/digital_operation_catalog.html，可以检查 facade 到 definition 的映射，并保存代表性的 Source 线路。
执行 Digital O1¶
O0 保持输入门顺序；显式 O1 执行确定性、精确的相邻重写，并返回前后 hash、指标和 lineage：
from cascaqit.digital import std, build_digital_program, optimize_digital_program
program = build_digital_program(
program_id="program.o1",
qubits=("q0",),
operations=(
std.rx(0.25).on("q0", operation_id="rx0"),
std.rx(0.75).on("q0", operation_id="rx1"),
),
)
optimization = optimize_digital_program(program)
assert optimization.program.circuit.operations[0].arguments == {"theta": 1.0}
assert optimization.report.transformations[0].transformation_kind == "rotation_merge"
CompilerPipeline(options=CompilerOptions(optimization_level=1)) 使用同一个重写结果，并把报告保存在编译结果 metadata。当前 O1 删除 identity 和严格零旋转；只在完整 modifier state 能证明等价时抵消相邻 inverse/self-inverse Application；并合相同 axis/operands 上相邻的数值旋转。True inverse pair 记录 inverse_pair_elimination 和相反 inverse parity 证据；Catalog 已证明的重复 self-inverse Application 记录 self_inverse_pair_elimination。power modifier 会保守地阻止这两类 predicate。O1 不跨中间操作重排，也不执行近似、符号或硬件专用重写。
运行 digital_o1_optimization.py 并传入 --output artifacts/digital_o1_optimization.html，可以比较 source 与 optimized 概率，并保存带 transformation 表格的 Canonical 线路。
测量与结果¶
完成 compose 和 transformation 后再添加测量：
measured = bound.measure_all(key="m")
result = measured.run(shots=32, seed=7, return_probabilities=True)
解释 counts 前先读取 result.metadata["bitstring_ordering"]["qubit_order"]。测量只能位于末端；当前不支持 mid-circuit measurement、reset、经典条件、feedback 或 dynamic control。
本页所有路径都在本地执行，提供 seed 后可复现。它们不会提交到汉原硬件或 CASCAQit Cloud，也不会访问网络端点或加载凭证。