API 概览¶
常用类型可以直接从 cascaqit 导入；包级 API 则用于明确类型和功能归属。
快速开始和示例使用根导入。编写较大的应用、测试或集成代码时，建议使用包级导入，让依赖关系更清楚。
以下内容描述当前 Alpha SDK 的公开接口。这些接口仍可能调整，也不表示真实硬件或云服务已经接通。
相关用户文档：快速开始、第一个程序、教程、QAOA 与 VQE、统一 Problem 编译器、重试与恢复、示例指南、标准实验可视化和当前限制。
建议先看 examples/learning/，再看 examples/user/ 中的完整示例；examples/release/ 只用于最短的安装包检查。
包根目录包含 59 个常用工作流导出，机器可读白名单位于 docs/reference/public_api_manifest.json。
| 领域 | 根导出 |
|---|---|
| 程序与控制 | AHSProgram、AtomRegister、Circuit、HybridProgram、SiteMask、SitePattern、VanDerWaalsInteraction、Waveform |
| 本地执行 | LocalAhsSimulator、LocalDigitalSimulator、LocalBackend、SimulationOptions、RetryPolicy、MockNeutralAtomTarget |
| 参数与噪声 | Parameter、ParameterManager、ParameterScan、NoiseChannel、NoiseModel |
| Observable | Observable、ObservableSet、PauliI、PauliProduct、PauliX、PauliY、PauliZ、PauliZZ |
| Problem 与算法 | GraphProblemIR、QUBOProblemIR、IsingModelIR、HamiltonianTerm、PauliHamiltonian、PauliMeasurementConfig、ReadoutCalibration、ReadoutMitigationConfig、SampledSelectionConfig、OptimizerConfig、SPSAConfig、SPSALearningRateCalibrationConfig、SPSAStoppingConfig、SPSAIterationIR、AdamConfig、AdamStoppingConfig、AdamIterationIR、QAOA、VQE、VariationalResult、VQESamplingBenchmarkConfig、VQESamplingBenchmarkResult、VQEStabilityConfig、VQEStabilityDiagnosticResult |
| 结果与报告 | ResultIR、build_result_view、build_counts_histogram、visualize |
| 异常 | CASCAQitError、ProgramValidationError、CapabilityError、BackendExecutionError |
Analog¶
from cascaqit import AHSProgram, AtomRegister, SiteMask, SitePattern
from cascaqit import VanDerWaalsInteraction, Waveform
from cascaqit import LocalAhsSimulator, MockNeutralAtomTarget
这些 API 用于构建原子阵列、定义波形、校验程序并运行本地模拟量子程序。
主要对象包括：AHSProgram、AtomRegister、SitePattern、VanDerWaalsInteraction、Waveform、LocalAhsSimulator 和 MockNeutralAtomTarget。
VanDerWaalsInteraction(c6=..., cutoff_radius=..., enabled=...) 在 AHSProgram 上声明以下静态相干项：
c6 的单位是 rad*um^6/us，坐标和截断半径的单位是 um；当 distance <= cutoff_radius 时纳入该原子对。enabled=False 会保留声明配置与标识，但不贡献原子对能量。C6 可以为正或负。一维阵列是同一个二维欧氏坐标模型的共线特例，因此任意一维、二维排布使用相同路径。
该相互作用会生成规范 Native IR，并由独立 Analog、Hybrid、精确密度矩阵和 trajectory 模拟执行。它是归属 crosstalk 通道的确定性 coherent 项，算符为 number_number；它与可选的 coherent XX 噪声通道相互独立，后者使用自己的 noise report。完整离线用法见 examples/user/van_der_waals_interaction.py。
AHSProgram.parameter() 返回带单位的参数声明。constant、linear、piecewise 和保形 PCHIP Waveform.interpolated() 都可接收这类参数与安全表达式；Waveform.concat() 用于组合兼容的非插值串行片段。参数必须先通过 bind() 绑定，之后才能调用 validate()、ValidatedAHSProgram.discretize() 或 run()；生成的 ProgramIR 只包含数值波形和逐位点权重。详见插值波形。
AHSProgram.local_detuning() 追加一条实验性的本地模拟项；重复调用时，各项按声明顺序相加。每个 SitePattern 必须且只能覆盖阵列中所有 filled 位点。数值权重或规范的无量纲参数会绑定为按 filled 位点排序的数值 IR。SiteMask.constant() 提供静态稀疏二进制寻址，SiteMask.piecewise() 则在指定时间切换活动位点；两者最终都生成规范的稠密 SiteAddressingIR。用法和限制见局域失谐。
AHSProgram.local_rabi() 追加一条实验性的逐位点 Rabi 振幅，并使用共享的数值相位或波形相位；重复调用时，各项按声明顺序相干叠加。规范的振幅、相位、加权模式参数和 constant/piecewise 二进制 mask 均参与 Target 校验、离散化、理想态/密度矩阵/轨迹执行、脉冲可视化、资源记录和离线编译。详见局域 Rabi 控制。
AtomRegister 支持 line、square、rectangular、triangular 和 custom 几何。不可变的 with_site_status() 转换会保留 filled、vacant、defect 与 loading-failed 布局，只有 filled 目标位点进入逻辑状态顺序。cascaqit.analog.SitePhasePattern 可为局域 Rabi 增加绑定后的逐位点弧度偏移。本地 Target 会生成带类型的控制计划，并检查并发、互斥、带宽、变化率和串扰策略。详见实验控制与原子阵列生命周期。
只有指定的 Target 快照能够提供所需的模式化通道时，CompilerPipeline.compile() 才接收离散化后的局域失谐或局域 Rabi ProgramIR。生成的 ReferenceCompiledProgramIR 是公开的离线参考数据，不是 ExecutionPackage、私有编译器输出或硬件载荷。
可选 Pulser 参考验证¶
from cascaqit.simulators import PulserReferenceBackend, PulserReferenceJob
from cascaqit.simulators.pulser_reference import (
PulserReferenceAdapter,
compare_pulser_reference,
)
PulserReferenceBackend 为冻结的单个位点全局 Analog 子集提供与 LocalBackend 相同的惰性 Job 接口，两者均返回标准 ResultIR。reference_run() 返回带类型的 Pulser 记录，用于比较状态保真度。真实执行需要安装 .[reference-pulser]。不支持的语义、缺失依赖、采样或随机种子问题会在求解前报错；默认导入不会加载 Pulser 运行时包。
Digital¶
from cascaqit import Circuit
Circuit 使用链式 API 构建小规模数字门程序，可在本地模拟并返回比特顺序和测量记录。原生 IR 类型仍从 cascaqit.digital 导入。
Circuit.parameter() 和安全表达式只存在于声明层，必须显式调用 bind()。可复用 Circuit 支持 append()、带完整量子比特映射的 compose()、inverse()、有界 repeat() 和受目标能力限制的 controlled()；只有全部参数均已绑定的 Circuit 才会生成只含浮点数的 DigitalProgramIR。
主要对象是 Circuit。高级参数值类型属于 cascaqit.digital，不从根包导出。详见 Digital Circuit 使用指南。
Hybrid 语法¶
from cascaqit.syntax import digital_block, analog_block, measurement_block
from cascaqit.syntax import program_syntax, analyze
实验性的包级前端用于声明程序块，并把受支持的 Python 语法降低为 ProgramSyntaxAST 和 SemanticProgramHIR。装饰器默认只读取函数签名；设置 lower_body=True 后还会捕获受限的声明函数体，再由 BlockDefinition.lower() 生成原生 Circuit 或 AHSProgram。分析过程不会执行该函数。
HybridProgram 是承载分析后 block 的语义编排模型：
from cascaqit import HybridProgram
program = HybridProgram.from_hir(analysis.hir)
Hybrid 参数¶
from cascaqit import Parameter, ParameterManager, ParameterScan
规范参数包支持带类型的声明、默认值、受限算术表达式、自动 Digital/Analog 目标和确定性扫描。HybridProgram.parameters 返回汇总后的 ParameterManager 视图。
本地 Hybrid 模拟¶
from cascaqit import HybridProgram, LocalBackend, SimulationOptions
from cascaqit import NoiseChannel, NoiseModel
from cascaqit.simulators import LocalHybridExecutionBuilder
from cascaqit.simulators import LocalHybridScanJob, LocalHybridScanJobResult
使用 HybridProgram.digital()/analog()/measure_all() 构造带类型的程序内容。LocalBackend.run(program)、run(program, params=...) 和 run(program, sweep=...) 分别执行静态程序、单组参数和参数扫描；程序快照、参数目标、编译前检查和末端测量绑定均自动完成。
通过 options=SimulationOptions(...) 控制 state method、integrator、dtype、CPU device、内存预算、worker、trajectory、容差、最大 accepted steps 和 seed。资源规划在创建 Job 前完成。Analog/Hybrid 的 state-vector、subspace 和 density 路径支持分段 DOP853 自适应积分，trajectory 保持固定步长。result.execution_config() 返回实际选择，result.solver_evidence() 返回真实 numerical work，result.state_transitions() 返回规范的状态/时间链，result.resource_usage() 返回 typed 资源观测。可执行 NoiseModel 会选择 exact density-matrix 或 batched trajectory；八类 canonical channel 覆盖 preparation、dephasing、gate、idle、crosstalk、Hybrid boundary、atom loss 和 readout，sweep 也可与 noise 组合。
简单 API 与高级 API 共用同一套实现。HybridProgram.analyze()、compile()、parameters、execution_builder() 和 to_ir() 均保留在同一个对象上。HybridProgramIR、LocalExecutionPlan、HybridBlockSimulator 和 LocalHybridExecutionBuilder 仍从各自所属包导入；IR 与执行计划不能直接传给后端。详见本地 Hybrid 模拟。
持久化本地 Job¶
from cascaqit import LocalBackend, RetryPolicy
配置 LocalBackend(store=...) 后，可使用 run(..., retry=RetryPolicy(...))、resume(job_id) 和 history(...) 保存、恢复并查询本地任务。详细历史记录与执行尝试类型仍从 cascaqit.backends 导入。详见重试、恢复与本地历史。
QAOA 与 VQE¶
from cascaqit import OptimizerConfig, QAOA, VQE
from cascaqit import HamiltonianTerm, PauliHamiltonian, VariationalResult
QAOA(...).run() 与 VQE(...).run() 都从 Problem 或算符开始，并返回同一种报告结构。QAOA 接收 MIS、MWIS、QUBO 和 Ising；VQE 接收 QUBO、Ising 和带类型的加权 Pauli Hamiltonian。两者都使用规范的 Circuit 参数，每次目标函数求值对应一个 LocalBackend Job 和一批 Observable；支持固定 seed 的多起点优化，最终采样使用独立 Job，所有记录保存在不可变的 VariationalResult 中。COBYLA、Nelder-Mead、Powell 和 L-BFGS-B 由 SciPy 执行，SPSA 与 Adam 使用 CASCAQit 原生循环。VQE 支持 HardwareEfficientAnsatz、CardinalityPreservingAnsatz 和参数化 custom Circuit。固定基数结果会在 cardinality_subspace 中保留逐组 weight 分布、保持率和采样违规数。
OptimizerConfig(method="SPSA", spsa=SPSAConfig(...)) 默认 directions_per_iteration=1，也可以让每轮执行多个完整正负扰动方向。cascaqit.algorithms 中的 SPSADirectionIR 保存每个 Rademacher 方向、正负参数、池化目标值和方向梯度；从包根导出的 SPSAIterationIR 保存平均梯度、两个及以上方向时的分量标准误、增益、投影更新、更新模长和求值偏移。精确目标的每个参数点使用一个 Backend Job；Digital VQE 也可以在理想执行或 canonical NoiseModel 下使用有限 shots QWC 测量，并固定 repeats 或在标准误阈值下有界自适应。带噪 sampled VQE 支持 Digital preparation、gate、idle、crosstalk 和 readout channel，模拟方法可选 auto、density_matrix 或 trajectory。ReadoutCalibration 与 ReadoutMitigationConfig 为 sampled estimator 提供显式 tensor-product linear-inverse 读出缓解，同时保留 raw counts。VQE.benchmark_sampling() 在配对初值与 seed 下比较理想精确、单次采样、固定 repeats 和自适应 repeats，再对每个采样策略选中的参数执行独立精确复测。
设置 SPSAConfig(learning_rate=None, learning_rate_calibration=SPSALearningRateCalibrationConfig(...)) 后，优化器会在初始点执行完整正负方向，用局部梯度 RMS 派生 learning-rate scale。保存的校准记录包含参数顺序、方向、平均梯度、梯度 RMS、目标首步更新 RMS、派生 scale、投影、偏移和实际成本。固定 scale 与自动校准二选一。校准支持精确、精确密度矩阵、理想 sampled 和带噪 sampled VQE，但不会顺带调整 perturbation、指数、repeats 或停止阈值，也不表示优化已经收敛。
SPSAStoppingConfig 可以在运行中检查完整的迭代窗口。必选检查包括中心代理值范围、更新模长和平均梯度模长；方向梯度标准误和采样目标标准误可以按需启用。第一个完整通过的窗口使用 termination.reason="stability_reached"，随后仍执行正常的最终中心估计。SPSAStoppingCheckIR、SPSAStoppingEvidenceIR 和 derive_spsa_stopping_evidence() 只从 cascaqit.algorithms 导出。保存的证据可以恢复并进入标准报告，但不是收敛或最优证明。
已完成的原生 SPSA VQE 可以调用 result.diagnose_stability(VQEStabilityConfig(...))。它只读取保存结果，检查末端目标范围、更新与梯度模长、采样标准误、repeat 停止和预算原因，不会重新运行 Backend。精确、理想 sampled 和带噪 sampled 结果共用这套保存统计，但诊断不会校正噪声偏差。选中 start 的结果为 stable、unstable 或 insufficient_evidence。这些状态只说明是否满足当前工程阈值，不证明基态、全局最优或严格收敛；非 SPSA 优化器暂不支持。
QAOA.gradient() 与 VQE.gradient() 对 RX/RY/RZ 仿射参数执行 occurrence-level parameter-shift。OptimizerConfig(method="L-BFGS-B", gradient=GradientConfig(...)) 会把同一条可执行 jacobian 路径交给 SciPy，原生 Adam 也使用这份梯度契约；两者都保存每个 ObjectiveGradientIR、shift Job、nfev、njev 和 Backend 总成本。QAOA 梯度支持理想或精确密度矩阵带噪 Digital 执行。VQE 还可传入 PauliMeasurementConfig，计算理想、带噪或读出缓解后的有限 shots 梯度，并保存完整协方差。Sampled VQE 梯度支持完整梯度的固定或有界自适应 repeats，可使用以下不确定度目标：
其中 Sigma 表示完整参数协方差矩阵。Adam 还能同时检查连续窗口内的更新模长和梯度不确定度。Sampled 梯度与 Adam 仅适用于 VQE，暂不支持 trajectory 精确目标、逐 occurrence 自适应分配、并行 shift、Analog 或 Hybrid 执行。
上面的导入用于常见算法调用。配对基准和稳定性诊断的配置与结果类型也从包根导出；逐 start 诊断 IR、基准运行 IR、梯度契约、规范 Ansatz 构造器、Problem 投影、解码和 baseline 辅助函数仍从 cascaqit.algorithms 导入。详见 QAOA 与 VQE。
统一 Problem 编译器¶
from cascaqit.algorithms import OptimizerConfig
from cascaqit.problems import ProblemCompiler, ProblemExecutionResult
analysis = ProblemCompiler().analyze(problem, target=target)
compiled = ProblemCompiler().compile(
problem,
mode="hybrid",
algorithm="qaoa",
target=target,
)
execution = compiled.run(
params={"gamma_0": 0.2, "beta_0": 0.3},
shots=256,
seed=7,
)
optimized = compiled.optimize(
optimizer=OptimizerConfig(max_evaluations=24, starts=3, seed=7),
initial_parameters={"gamma_0": 0.2, "beta_0": 0.3},
shots=256,
seed=7,
)
ProblemCompiler 让三种模式共用同一个规范化 Problem、逻辑 Hamiltonian、Target-aware 映射计划、逻辑顺序和 decoder。当前接受 digital + qaoa、digital + vqe、hybrid + qaoa 和 analog + qaa。Digital QAOA 和固定层数 VQE 生成 Circuit；Unified VQE 支持默认模板、HardwareEfficientAnsatz、CardinalityPreservingAnsatz 和参数化 custom Circuit。Hybrid QAOA 生成 HybridProgram，Analog QAA 生成 AHSProgram。dad 是当前 Hybrid 拓扑，ahs 是 Analog 程序模型；二者都不是算法，也不通过公开 strategy 参数传入。
编译结果提供 run()、evaluate()、参数绑定、结果解码，以及两种互斥的 optimize() 用法：执行用户给定参数点，或运行配置好的连续优化。所有模式都支持可复现的多起点优化，QAOA 和内置 VQE 还支持分层初始化。Digital QAOA/VQE 另外提供 gradient() 和 L-BFGS-B，Digital VQE 还支持原生 Adam；Analog 与 Hybrid 会在执行前拒绝梯度。ProblemCompiler.optimize_layers() 对连续的 Digital QAOA/VQE 或 Hybrid QAOA 层数各执行一次优化，再按固定预算改善规则选层。有限 shots Digital VQE 必须使用 SPSA 或 Adam，并配置独立候选确认；选层读取确认能量，下一层继承确认参数。optimize_layers_repeated() 对每层执行多次独立完整优化，按 repeat index 迁移参数，并根据单侧 Student-t 改善下置信界选层。repeats 不等于 optimizer starts、shots 或 trajectories；optimizer seed 保留为 None，各 run seed 由实验根 seed 派生。ProblemLayerExperimentResult 保存单次选层的目标来源，以及目标求值、确认和末端采样成本。ProblemRepeatedLayerExperimentResult 保存全部执行、逐层统计、配对比较、选中层和停止原因。详见统一 Problem 编译器。
结果¶
from cascaqit import build_counts_histogram, build_result_view
from cascaqit.results import InteractionReportIR, ResultEvidenceIR, ResultViewIR
from cascaqit.results import SimulationExecutionConfigIR, SimulationResourceUsageIR
这些辅助函数用于查看 counts、诊断、运行记录、执行配置、资源用量和可视化派生视图。单次本地 ResultIR 通过 execution_config() 和 resource_usage() 返回带类型的 IR。interaction_report() 返回唯一一份已执行的 Analog 相互作用报告或 None；包含多个 Analog block 的 Hybrid 结果应使用 interaction_reports()。每个 InteractionReportIR 保存实际执行的配置、物理分类、几何与 pair table 哈希、活动原子数、有效 pair 数、距离与强度摘要，以及真实状态演化标志。扫描汇总在元数据中保存执行和资源字典，每个已完成项保留自己的执行证据。Pulser、硬件 mock 和云端结果不会伪造本地规划器数据。
结果辅助函数只读取 ResultIR。ProgramIR 和 ResultIR 仍是事实源；结果视图、直方图、可视化元数据和报告均由它们派生。
标准实验可视化¶
from cascaqit import visualize
report = visualize(result, program=program, output="experiment.html")
visualize() 自动识别 Digital、Analog、Hybrid、Sweep、Comparison、Batch、VariationalResult、ProblemExecutionResult、ProblemLayerExperimentResult 和 ProblemRepeatedLayerExperimentResult 输入，并返回 ExperimentReport。Analog 与 Hybrid 报告显示原子几何与状态、活动位点顺序、合并控制波形、逐位点寻址帧、控制计划与诊断、相位模式设计值和实际使用值。算法报告只读取已有的目标函数、采样、解码、基准、完整 Ansatz 和梯度证据，不会重新运行优化器；梯度视图显示计划、参数分量、L2 范数、正负偏移能量、nfev/njev 与 Backend 成本。Problem 报告从保存的执行上下文增加规范化目标、逻辑 Hamiltonian、适用时的罚项充分性证明、映射、Hamiltonian 项分配、生成的原生程序，以及适用时的 VQE Definition、线路/契约哈希、候选解与期望能量分解、参数历史和基准。多个已完成的 Problem 结果只要 problem_hash 和逻辑顺序一致，就能对比层数、优化器配置或 Digital QAOA、Digital VQE、Hybrid QAOA、Analog QAA 路线。单次层数实验报告显示固定预算改善记录；重复层数实验还会显示原始 repeat 目标值、Student-t 区间、配对下置信界、run seed 和完整优化/求值成本。当前只支持保存为 HTML。
ExperimentReport 归属 cascaqit.visualization，根包只导出高频入口 visualize。报告内容和边界详见标准实验可视化。
运行时与后端接口¶
from cascaqit import LocalBackend
from cascaqit.backends import ExecutionBackendCapabilityProtocol
from cascaqit.backends import ExecutionBackendProtocol, ExecutionJobProtocol
from cascaqit.backends import ScanExecutionJobProtocol
LocalBackend 与可选的 PulserReferenceBackend 都实现同一个单任务结构协议，并分别返回自己的能力 IR。LocalBackend 还支持聚合扫描，其结果为 LocalHybridScanJobResult，不是单任务 ResultIR。需要自定义状态或 Bundle 时仍可使用 LocalHybridExecutionBuilder；JobRuntime 与 LocalHybridSimulator 属于内部或旧式路径，不是推荐的用户入口。
当前后端 API 只覆盖接口约定和 dry run（只构建或校验，不实际执行），不会向真实汉原硬件或 CASCAQit Cloud 提交任务。
这些 API 不访问网络端点，不加载凭证，不读取对象存储中的制品字节，不签发带签名的 URL，不上传发布包，也不执行发布签名。
离线硬件提交¶
先从 cascaqit.compiler 导入 CompilerPipeline，得到 ReferenceCompiledProgramIR；再从 cascaqit.submission 导入 HardwareSubmissionBuilder，构建带校验和的 HardwareSubmissionIR。公开安装包只支持 Digital 和 Analog 提交数据构建，不包含私有 Compiler Service、执行包、硬件载荷、Gateway、凭证或服务端点。
离线硬件提交契约给出了可运行示例，并区分公开编译、提交数据构建和仓库内 mock 验证流程。
Interop¶
from cascaqit.interop import export_program, import_program, render_openqasm3_subset
from cascaqit.interop.openqasm3_subset import parse_openqasm3_subset
受限 OpenQASM 互操作支持 SDK 文档描述的本地数字子集。不支持的语法应通过诊断和显式校验失败处理。
完整 OpenQASM 语法、defcal、timing 和 dynamic control 不属于当前版本范围。