本地 Hybrid 模拟¶
先运行覆盖理想态、物理噪声和参数扫描的完整示例：
python3 examples/user/complete_physical_hybrid_demo.py \
--output artifacts/complete_physical_hybrid_report.html
HybridProgram 直接持有 typed Digital 和 Analog payload，LocalBackend.run() 是普通用户唯一的提交入口：
from cascaqit import HybridProgram, LocalBackend, SimulationOptions
program = (
HybridProgram("demo")
.digital("prepare", circuit)
.analog("evolve", ahs_program)
.digital("correct", correction)
.measure_all()
)
job = LocalBackend(seed=7).run(
program,
shots=32,
options=SimulationOptions(method="auto", max_memory_bytes=2_000_000_000),
)
result = job.result()
print(result.counts)
print(result.metadata["simulation_resource_estimate"])
payload 在加入程序时会被快照；之后修改原始 Builder 不会改变 HybridProgram。高级用户仍可从同一对象访问 analyze()、compile()、parameters、execution_builder() 和 to_ir()。
参数与扫描¶
Circuit 和 AHSProgram 声明的参数会自动汇总。同名且定义相同的参数共享一份声明；定义冲突会在执行前失败。每个持有参数的 block 都会自动生成 target。
from cascaqit import ParameterScan
single = backend.run(program, params={"theta": 0.2}, shots=32)
scan = ParameterScan.explicit(
scan_id="scan.theta",
points=({"theta": 0.1}, {"theta": 0.4}),
)
sweep_job = backend.run(program, sweep=scan, shots=32)
sweep_result = sweep_job.result()
print(sweep_result.counts)
params 与 sweep 互斥。scan 没有固定点数上限，由内存预算决定可执行规模。continue_on_error 使用内存受限 worker pool，严格 fail_fast 保持串行，确保标记为 not_run 的点从未启动；两种策略都按 scan index 稳定返回结果，并从 root seed 为每个点派生独立 seed。只有自定义初态或直接控制 Bundle 时才需要 execution_builder(parameterized=True)。
自适应精度与状态溯源¶
先运行求解器对照示例：
python3 examples/user/adaptive_solver_and_lineage.py
Analog 或 Hybrid 使用 state-vector、subspace、density-matrix 时，integrator="auto" 会选择 DOP853 自适应积分器。实验需要固定数值策略时，可以显式设置：
result = backend.run(
program,
shots=32,
options=SimulationOptions(
integrator="adaptive_dop853",
rtol=1e-9,
atol=1e-11,
max_steps=10_000,
),
).result()
print(result.execution_config())
print(result.solver_evidence())
print(result.state_transitions())
求解器会在 waveform knot 和 site-addressing frame time 精确结束当前分段，再继续积分。solver_evidence() 返回 accepted steps、函数求值次数、分段数、步长范围、终止原因，以及容差是否真的参与计算。SciPy 不公开 DOP853 内部 rejection count，因此 CASCAQit 将它标记为不可用，不做推算。
state_transitions() 为每个量子 block 返回一条规范记录。Digital block 不推进逻辑时间，Analog block 按 duration 推进；相邻 transition 的输出/输入 state hash 必须相等，首尾 hash 还要与顶层 initial/final reference 一致。终端测量只记录为 trace event，不伪造量子态 transition。
纯 Digital gate 执行不需要时间积分。Trajectory 的 jump probability 仍依赖固定时间片，因此当前只支持固定步长；显式请求 adaptive trajectory 会在规划阶段失败。fixed_step_krylov 可用于受控对照，并明确记录 tolerance_applied=False。
物理噪声¶
可执行噪声 API 已纳入精简根 API：
from cascaqit import NoiseChannel, NoiseModel, SimulationOptions
noise = NoiseModel(
"noise.demo",
(
NoiseChannel.preparation(0.01),
NoiseChannel.dephasing(0.2),
NoiseChannel.gate(0.01),
NoiseChannel.atom_loss(0.02, targets=("q1",)),
NoiseChannel.readout(0.02, p10=0.03),
),
)
result = backend.run(
program,
params={"theta": 0.2},
noise=noise,
shots=256,
options=SimulationOptions(trajectories=256, seed=7),
).result()
print(result.counts)
print(result.observables)
print(result.metadata["noise_report"])
没有 atom loss 时，method="auto" 会在资源预算允许时优先选择 exact density-matrix，否则使用 trajectory；atom loss 必须使用 trajectory，因为 density state 没有真空占据轴。按执行顺序记录的 NoiseReport 会区分物理态演化与只修改测量结果的 readout noise。同一个 canonical noise model 也可以与 sweep=... 一起提交：每个参数点使用独立派生 seed，并返回自己的 noise report、state chain、counts、Observable 和置信区间。Sweep concurrency 统一管理 worker 预算，因此 trajectory item 各自只使用一个内部 worker，不会嵌套创建 worker pool。
当前边界¶
SimulationPlanner 不声明固定产品 site 上限。它根据程序语义和默认 80% 主机内存预算选择 state representation 与 integrator，并在分配大数组或创建 scan Job 前拒绝不支持或超预算的任务；DOP853 workspace 也计入估算。并行 scan 的 aggregate 归属 scan concurrency 和 root seed，每个 item 记录一个 kernel worker 和与调度顺序无关的派生 seed。result.resource_usage() 记录 wall time、进程 peak RSS、baseline、增量、规划估算和可计算时的估算误差。
可扩展 engine 通过 tensor axis 执行 Digital gate；Analog block 的同一个 matrix-free Hamiltonian 可由自适应 DOP853 或固定步长 Krylov 消费。D-A-D Hybrid block 共享同一 state，并公开规范的 transition/reference chain。Apple M4 已验证参考运行覆盖 24-qubit Digital、18-site 理想 Analog/Hybrid、10-site exact density 和 16-site/256-trajectory 带噪 Hybrid；这些数字是参考规模，不是固定上限。
HybridProgramIR 和 LocalExecutionPlan 是序列化与规划产物，不能直接传给 Backend.run()。本地路径不会访问硬件、云服务、凭证或网络。