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,
)
Submit Digital, Analog and Hybrid programs for execution on the local CPU. run() returns a job handle; job.result() executes the job or reads its result. Use this entry point for noise, parameter scans, resource planning and job recovery.
seed supplies the backend default random seed, and target supplies target constraints for analog programs. analog_time_steps is a positive integer controlling fixed-step analog discretization. kernel_threads defaults to 1; larger values cannot be combined with scans or noisy execution. created_at can fix result timestamps, while backend_id identifies the backend in results and stored jobs. Target specifications do not connect to physical devices.
store is a local SQLite storage path. Set it to retain jobs, query history and restore handles. The run arguments retry and idempotency_key also require a store. Keep both the database and its associated result files for recovery.
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}
See HybridProgram for scan inputs and SimulationOptions for numerical and resource settings.
Return LocalBackendCapabilityIR describing supported programs, methods, noise and scans. These capabilities do not guarantee sufficient host memory; each submission still requires planning and preflight.
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
)
Accept Circuit, DigitalProgramIR, AHSProgram, ProgramIR or HybridProgram. Preflight returns a single-run or scan job, not ResultIR. Use params for one binding or sweep for a Hybrid scan; do not supply both. Raw Hybrid IR and compiled plans are not executable inputs; restore them with HybridProgram.from_ir() first. observables requests observables and noise accepts NoiseModel; preflight checks supported combinations.
Explicit shots overrides config.shots, with 1000 as the default. Seed precedence is run.seed, config.seed, backend.seed, options.seed, then 0. config is cascaqit.native_ir.SimulatorConfigIR; use options for planning. Scan failure policy is fail_fast or continue_on_error; inspect individual failures with the latter. Persistent jobs accept RetryPolicy and an idempotency key; a conflicting reuse does not silently replace the old request. Invalid inputs, resource limits or unsupported capabilities can raise structured errors before a handle is returned; execution can also fail in result().
Restore a handle from the definition saved in store. Completed jobs can read saved results; unfinished jobs follow persistent execution rules. Restoring a handle does not start a background service. A missing store or mismatched backend_id raises CapabilityError; unknown job IDs fail in the store.
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
Return a paginated JobHistoryPage without executing jobs. Set limit and use the response cursor for the next page. Filters cover status, program kind, single-run or scan jobs and creation time, using time strings accepted by the store. A missing store raises CapabilityError.