LocalBackend¶
from cascaqit import LocalBackend
LocalBackend ¶
LocalBackend(
seed: int | None = None,
target: TargetSpec | None = None,
analog_time_steps: int = 400,
created_at: str | None = None,
backend_id: str = "local.simulator",
store: str | PathLike[str] | None = None,
kernel_threads: int = 1,
)
统一提交数字、模拟和 Hybrid 程序，在本机 CPU 上执行。run() 返回任务句柄，调用 job.result() 才执行或读取结果。需要噪声、参数扫描、资源规划或任务恢复时，优先使用这个入口。
seed 是后端默认随机种子；target 指定模拟程序的目标约束。analog_time_steps 控制固定步长模拟的离散规模，必须是正整数。kernel_threads 默认 1，大于 1 时不能与参数扫描或噪声执行合用。created_at 可固定结果时间，backend_id 标识结果与持久化任务所属的后端。这里的目标规格不连接真实设备。
store 是本地 SQLite 存储路径。提供它后，可以保存任务、查询历史和恢复句柄；retry 与 idempotency_key 也要求配置 store。保留数据库及关联结果文件才能恢复完整任务。
from pathlib import Path
from tempfile import TemporaryDirectory
from cascaqit import Circuit, LocalBackend
circuit = Circuit(1).x(0).measure_all()
with TemporaryDirectory() as directory:
backend = LocalBackend(store=Path(directory) / "jobs.sqlite", seed=7)
job = backend.run(circuit, shots=32, job_id="learn_x")
assert job.result().counts == {"1": 32}
assert backend.resume("learn_x").result().counts == {"1": 32}
扫描输入见 HybridProgram，数值与资源选项见 SimulationOptions。
返回 LocalBackendCapabilityIR，描述支持的程序、方法、噪声与扫描。能力声明不保证当前机器的内存足够；每次提交仍需规划与预检。
run ¶
run(
program: HybridProgram,
*,
params: None = None,
sweep: ParameterScan,
noise: NoiseModel | None = None,
options: SimulationOptions | None = None,
shots: int | None = None,
seed: int | None = None,
job_id: str | None = None,
config: SimulatorConfigIR | None = None,
observables: ObservableSet | None = None,
failure_policy: LocalHybridScanFailurePolicy = "fail_fast",
retry: RetryPolicy | None = None,
idempotency_key: str | None = None,
) -> LocalHybridScanJob | PersistentLocalHybridScanJob
run(
program: Circuit
| DigitalProgramIR
| AHSProgram
| ProgramIR
| HybridProgram,
*,
params: Mapping[str, bool | int | float] | None = None,
sweep: None = None,
noise: NoiseModel | None = None,
options: SimulationOptions | None = None,
shots: int | None = None,
seed: int | None = None,
job_id: str | None = None,
config: SimulatorConfigIR | None = None,
observables: ObservableSet | None = None,
failure_policy: LocalHybridScanFailurePolicy = "fail_fast",
retry: RetryPolicy | None = None,
idempotency_key: str | None = None,
) -> ExecutionJobProtocol
run(
program: Circuit
| DigitalProgramIR
| AHSProgram
| ProgramIR
| HybridProgram,
*,
params: Mapping[str, bool | int | float] | None = None,
sweep: ParameterScan | None = None,
noise: NoiseModel | None = None,
options: SimulationOptions | None = None,
shots: int | None = None,
seed: int | None = None,
job_id: str | None = None,
config: SimulatorConfigIR | None = None,
observables: ObservableSet | None = None,
failure_policy: LocalHybridScanFailurePolicy = "fail_fast",
retry: RetryPolicy | None = None,
idempotency_key: str | None = None,
) -> (
ExecutionJobProtocol
| LocalHybridScanJob
| PersistentLocalHybridScanJob
)
接受 Circuit、DigitalProgramIR、AHSProgram、ProgramIR 或 HybridProgram。预检后返回单次或扫描任务；不会直接返回 ResultIR。params 绑定一次参数，sweep 提交 Hybrid 参数扫描，两者不要同时提供。原始 Hybrid IR 或编译计划不能直接执行，先用 HybridProgram.from_ir() 恢复。observables 请求观测量，noise 使用 NoiseModel；支持组合仍由预检确认。
显式 shots 优先于 config.shots，均未提供时为 1000。随机种子依次取 run.seed、config.seed、backend.seed、options.seed，最后为 0。config 是 cascaqit.native_ir.SimulatorConfigIR；规划选项用 options。扫描失败策略为 fail_fast 或 continue_on_error；后者仍需逐项检查失败。持久化任务可指定 RetryPolicy 和幂等键，同键冲突不会静默替换旧请求。参数、资源或能力不满足时可能在返回句柄前抛出结构化异常，执行失败也可能在 result() 时出现。
从 store 中保存的定义恢复任务句柄。已完成任务可读取保存的结果；未完成任务按持久化执行规则处理，恢复句柄本身不会启动后台服务。缺少 store 或 backend_id 不匹配时抛出 CapabilityError，未知任务 ID 由存储层报错。
history ¶
history(
*,
limit: int = 20,
cursor: str | None = None,
statuses: tuple[JobState, ...] | None = None,
program_kinds: tuple[JobProgramKind, ...] | None = None,
job_kinds: tuple[JobKind, ...] | None = None,
created_after: str | None = None,
created_before: str | None = None,
) -> JobHistoryPage
返回分页 JobHistoryPage，不执行任务。用 limit 控制页大小，并将响应中的游标用于下一页；可按状态、程序类型、单次或扫描任务及创建时间筛选。时间边界使用存储支持的时间字符串。未配置 store 时抛出 CapabilityError。