将同一个相位绑定到两类程序块¶
用一个参数同时设置 Digital RZ 门的角度和 Analog 驱动的相位。先检查绑定值究竟写到了哪里，再判断测量概率是否应随之变化。阅读前请完成共享量子态和数字线路参数绑定，并在安装好的环境中从仓库根目录运行。
同名参数必须表示同一物理量¶
Digital 程序块制备 RZ(φ) H |0⟩，其 Bloch 向量为 (cos φ, sin φ, 0)。Analog 程序块采用零失谐，驱动相位也为 φ，旋转轴同样是 (cos φ, sin φ, 0)。初态恰好是该驱动的本征态，演化只改变整体相位。因此，共享相位变化后，Z 基测量的两个概率仍应相等。
两个声明都使用名称 phase，类型为浮点数，单位为弧度，默认值为 0.2，范围为 [-1, 1]。HybridProgram.parameters 将兼容的声明合并为一个参数，并记录两个目标程序块。同名但声明冲突时会报错，不会自动当成两个独立变量。
"""让 Digital 和 Analog block 共用一个规范参数。
参数名、类型、单位、边界和默认值共同组成 schema。两类 block 中的相位定义一致时，
``HybridProgram`` 可以一次完成绑定，不需要按模式分别转换参数。
"""
from __future__ import annotations
import json
from typing import cast
from cascaqit import (
AHSProgram,
AtomRegister,
Circuit,
HybridProgram,
LocalBackend,
Waveform,
)
def main() -> None:
"""声明、合并、绑定并执行一个跨 block 参数。"""
digital = Circuit(1, program_id="lesson.hybrid.parameters.digital")
digital_phase = digital.parameter(
"phase", default=0.2, lower_bound=-1.0, upper_bound=1.0
)
digital.h(0).rz(digital_phase, 0)
analog = AHSProgram(
AtomRegister.line(count=1, spacing=5.0),
program_id="lesson.hybrid.parameters.analog",
)
analog_phase = analog.parameter(
"phase", unit="rad", default=0.2, lower_bound=-1.0, upper_bound=1.0
)
analog.drive(
rabi=Waveform.constant(0.4, duration=0.1),
detuning=Waveform.constant(0.0, duration=0.1),
phase=analog_phase,
)
program = (
HybridProgram("lesson.hybrid.parameters")
.digital("prepare", digital)
.analog("evolve", analog)
.measure_all()
)
manager = program.parameters
bound = program.bind({"phase": 0.35})
result = LocalBackend(analog_time_steps=4).run(bound, shots=16, seed=102).result()
digital_ir = cast(Circuit, bound.payload("prepare")).to_ir()
analog_ir = cast(AHSProgram, bound.payload("evolve")).measure().to_ir()
payload = {
"track": "hybrid_researcher",
"level": "foundation",
"lesson": "canonical_parameters",
"facts": {
"schema_names": [item.name for item in manager.schema.parameters],
"target_count": len(manager.targets),
"digital_phase": digital_ir.circuit.operations[1].arguments["theta"],
"analog_phase": analog_ir.hamiltonian.phase,
"probabilities": result.probabilities,
"counts_total": sum(result.counts.values()),
},
"boundaries": {
"hardware_execution": False,
"cloud_execution": False,
"network_accessed": False,
"credentials_loaded": False,
},
}
print(json.dumps(payload, sort_keys=True))
if __name__ == "__main__":
main()
python3 examples/user/tracks/hybrid_researcher/02_foundation_canonical_parameters_zh.py
program.bind({"phase": 0.35}) 返回绑定后的 Hybrid 程序。需要接住这个返回值，原程序仍可作为模板复用。Digital 角度和 Analog 相位都会得到 0.35 rad。
同时检查绑定值和测量概率¶
{
"boundaries": {
"cloud_execution": false,
"credentials_loaded": false,
"hardware_execution": false,
"network_accessed": false
},
"facts": {
"analog_phase": 0.35,
"counts_total": 16,
"digital_phase": 0.35,
"probabilities": {
"0": 0.5,
"1": 0.4999999999999999
},
"schema_names": [
"phase"
],
"target_count": 2
},
"lesson": "canonical_parameters",
"level": "foundation",
"track": "hybrid_researcher"
}
依次查看 schema_names、target_count、digital_phase 和 analog_phase：它们分别说明声明了什么参数、有几个目标，以及各目标实际收到的数值。不要把 bound.parameters.assignments 当成绑定回执。Hybrid 参数管理器会从程序块的声明重新组织参数信息，成功绑定后，这个字典仍可能为空。
脚本通过 bound.payload(...) 读取程序块的副本。为了用公开的独立 Analog to_ir() 接口查看内容，脚本给这个副本补上测量，使其成为完整程序。这一步只用于检查副本，不会在已经运行的 Hybrid 实验中插入中途测量。
probabilities 应接近 {"0": 0.5, "1": 0.5}，16 次采样不一定各得 8 次。仅凭等概率分布，也不能证明绑定正确：多种写错的程序同样可能得到均匀分布。数值参数和物理预测需要一起检查。
改变参数，或让两个相位分开¶
- 绑定
phase=-0.6，预测两个程序块中的数值及 Z 基概率。 - 绑定越界值
phase=1.2，读取绑定阶段的诊断。 - 把 Analog 驱动中的
phase=analog_phase改成固定的phase=0.0，Digital 仍绑定0.35，预测新的P(1)。
核对思路
第一项中两个数值都变为 -0.6，理想概率仍各为一半。第二项报 HYBRID_PARAMETER_BIND_INVALID。第三项中 Analog 绕 X 轴旋转，而初始 Bloch 向量具有 Y 分量。脉冲面积为 θ = 0.4 × 0.1 = 0.04 rad，所以 P(1) = [1 − sin(0.35) sin(0.04)]/2 ≈ 0.493144。共享相位会改变实验的物理约束，并非只是少写一个变量。
需要独立调节两个相位时，应使用不同参数名。Hybrid 参数指南说明了声明和绑定接口。下一课用参数扫描执行多组绑定，并把结果准确对应回各参数点。