Skip to content

Limitations

This page describes constraints on program construction, simulation, compilation and result analysis. Read them alongside the interfaces, parameter units and execution settings used by your experiment.

Analog parameters use explicit rad/us or rad units. Their expressions support same-unit addition/subtraction and finite scalar multiplication/division, without unit conversion or arbitrary Python evaluation. Waveform.interpolated() uses fixed shape-preserving PCHIP semantics. Waveform.concat() composes non-interpolated serial segments within the constant or linear family, up to 1024 result points; it does not mix families, overlap segments, or schedule parallel channels. AHSProgram.run() is an offline Local AHS convenience path, not a remote Backend or hardware Job API. Its optional O1 removes only exactly zero local control terms; it does not rewrite global controls or perform target-specific compilation.

Circuit.run(), AHSProgram.run(), and single-bind HybridProgram.run() accept optimization_level=0 | 1. O1 is an exact Canonical IR pre-execution rewrite and records evidence in ResultIR.metadata; it is not Target lowering, routing, scheduling, or Physical compilation. Hybrid O1 does not yet support parameter sweeps.

Current supported local SDK paths:

  • Native analog AHS program construction, validation, discretization, and local simulation.
  • Experimental ordered local detuning terms with static weighted patterns or constant/piecewise binary masks, target validation/discretization, and Local AHS or Hybrid simulation.
  • Experimental coherent local Rabi terms with static weighted patterns or constant/piecewise binary masks, amplitude plus shared phase, and ideal/density/trajectory Local AHS or Hybrid simulation.
  • Line, square, rectangular, triangular, and custom register geometry with immutable filled/vacant/defect/loading-failed snapshots, hash-linked lifecycle validation, and one active-site order across simulation, measurement, Result, and reports.
  • Numeric or parameterized per-site local-Rabi phase offsets consumed by validation, discretization, reference compile, state-vector/subspace/density/trajectory/Hybrid kernels, Result evidence, and standard reports.
  • Program-derived public control schedules with concurrency, mutual-exclusion, bandwidth, slew-rate, and crosstalk-policy diagnostics against declared local Target facts.
  • Offline public reference compile for typed local detuning and local Rabi on the explicit local target, including logical operation/schedule/channel/source/resource projections.
  • Public checksummed HardwareSubmissionIR construction for supported Digital and Analog reference compiles, plus a repository-only deterministic mock Compiler Service/Gateway/result-sanitization chain.
  • Native digital gate program construction and local state-vector simulation.
  • Versioned Digital Operation Definition/Application/Catalog contracts, typed argument normalization, standard derived facades and modifiers, deterministic normalization for built-in QFT/H-layer/GHZ-preparation Composite operations, modifier-safe exact adjacent O1 rewrites with lineage, QAOA Domain Plans with deterministic logical schedules, and read-only Source/Canonical/Native/Physical circuit visualization snapshots.
  • Experimental internal shared-state kernels for continuous Digital and Analog pure-state evolution.
  • Experimental cascaqit.syntax decorators, Syntax AST, Semantic HIR, source maps, and pre-execution diagnostics.
  • Opt-in lowering of allowlisted Digital and global Analog decorator body declarations into native Circuit / AHSProgram objects without executing user functions.
  • Experimental user HybridProgram, typed Block DAG, and deterministic local plan compilation.
  • Experimental ParameterManager, safe expressions, explicit Digital / Analog targets, deterministic scans, and argument projection.
  • Experimental unified LocalBackend.run() for lazy, cached Circuit, AHSProgram, and typed HybridProgram Jobs, including single binds and resource-planned scans.
  • Opt-in SQLite-backed local retry, cross-instance/process resume, child-granular Hybrid sweep recovery, and filtered immutable Job history with checksum sidecars.
  • NumPy/SciPy runtime dependencies, immutable state-vector/density/trajectory/subspace array contracts, and resource-driven planning before Job creation or large-array allocation.
  • Segmented DOP853 integration for Analog/Hybrid state-vector, blockade-subspace, and density-matrix evolution, with executed solver evidence and canonical Digital/Analog/Hybrid state transitions.
  • Canonical physical NoiseChannel / NoiseModel execution for single Digital, single Analog, and D-A-D Hybrid programs, with eight channel types, automatic density/trajectory selection, and ordered NoiseReport evidence.
  • Experimental LocalHybridExecutionBuilder for native user objects, parameter factories, strict serial fail-fast scans, and memory-bounded parallel continue-on-error scans across reference and scalable ideal engines.
  • Optional Pulser reference Backend/Job execution for one filled site, a global Rydberg drive, supported waveforms, exact ResultIR, typed run evidence, state fidelity, and Z comparison.
  • Mock runtime and backend contracts for packaging, traceability, and result inspection.
  • Structured ResultIR, DiagnosticsIR, run trace, result view, and visualization derived views.
  • Typed Pauli Observable batches for Digital, Analog, Hybrid, exact density, trajectory, and sweep child results, with explicit estimator and source evidence.
  • Fixed-parameter VQE energy estimation and sampled SPSA for standalone or Unified Problem Digital VQE through stable QWC grouping, explicit X/Y/Z basis rotations, one ideal local Digital Backend Job per group, covariance-aware uncertainty, fixed or bounded standard-error-driven objective repeats, optional learning-rate scale calibration, independent candidate confirmation, and standard reports.
  • Unified Target-aware Problem compilation for Graph, MIS, MWIS, QUBO, and Ising inputs to Digital QAOA/VQE, multi-layer Hybrid D-A-D QAOA, or fully expressible Analog QAA, with shared local execution, decoding, parameter-set evaluation, and Problem reports.
  • Restricted OpenQASM interop for supported local digital subsets.

For day-to-day use, start with examples/learning/, continue with examples/user/, and reserve examples/release/ for short package checks during release review or installation verification.

The current release does not support:

  • Full OpenQASM grammar, defcal, timing, or dynamic control.
  • Partial parameter binding, arbitrary Python expressions, callable parameters, complex values, or general symbolic values in std. Executable gradients cover only supported affine RX/RY/RZ expressions.
  • Mid-circuit measurement, reset, classical conditions, feedback, or dynamic control in the user-facing Circuit builder.
  • General unitary synthesis, ancilla allocation, or approximate controlled synthesis. Circuit-level control supports the built-in static Circuit gate set, including H, parameterized rotations, and nested controls, but does not establish hardware Target support.
  • General custom Composite factories or template interpretation, Operation Palette, automatic decomposition-rule selection, routing, or provider-native matrix/calibration extensions. Built-in QFT, H-layer, and GHZ-preparation normalization is executable, but it is not a general user-defined Composite lowering engine.
  • Recovery of facade spelling from canonical DigitalProgramIR alone. Source labels require the originating Circuit or an explicitly matching ProgramSourceMapIR; otherwise visualization uses canonical labels and reports unavailable evidence. Source Map data is display-only and cannot drive execution.
  • Physical Digital scheduling with real start times, durations, channels, or calibration. Physical circuit visualization remains explicitly not_bound; standalone and standard-report circuit renderers do not provide interactive stage tabs, Composite expansion, or long-circuit virtualization.
  • Continuous or parameterized mask timing/topology, production local scheduling, private/hardware lowering, or local-control decorator/Pulser lowering. Piecewise masks currently use numeric frame times and step interpolation; public control schedules do not allocate production channels or bind private calibration.
  • Hybrid hardware execution, parallel blocks, dynamic control, feedback, or mid-circuit measurement.
  • Hybrid hardware submission. Raman channels are explicitly unsupported and DMM channels are IR-only; neither has a scheduler or numerical runtime consumer.
  • Adaptive trajectory jump-time integration and GPU/MPS execution. Trajectory evolution intentionally remains fixed-step.
  • General symbolic, reverse-mode, adjoint, Analog, or Hybrid differentiation. Occurrence-level parameter-shift supports affine Digital RX/RY/RZ parameters. QAOA supports ideal or exact-density noisy gradients; VQE additionally supports finite-shot ideal, noisy, and readout-mitigated gradients. Sampled QAOA and parameter-dependent-noise gradients are not supported.
  • Persistent parameter scans do not provide remote Job retrieval, cross-host scheduling, or hardware/cloud execution. Noisy trajectory scans intentionally use one internal trajectory worker per concurrent scan item to avoid nested worker pools.
  • Local resource usage uses the process high-water RSS supplied by the host. If earlier process work already set a higher watermark, estimate error is unavailable; concurrent scan-item RSS is owned by the aggregate scan and is not attributed to individual points.
  • Pulser reference validation for two or more sites, Hybrid state handoff, local addressing, noise, parameter scans, sampling counts, or general third-party backend use.
  • General commuting-group Clifford diagonalization or mid-circuit Observable capture. Finite-shot VQE uses QWC groups with explicit local basis rotations and supports ideal or noisy Digital execution, native SPSA or Adam, uniform, coefficient-L1, or pilot-variance allocation, and explicit tensor-product readout mitigation. SPSA supports multiple directions and fixed or bounded standard-error-driven objective repeats. Adam uses a complete sampled parameter-shift gradient with covariance, but each shift point currently executes once.
  • General Problem minor embedding, gadget or quantum-wire construction, automatic layout search, alternate Hybrid topology, non-commuting Trotter split, Analog/Hybrid noisy Problem optimization, trajectory or shot-noise objectives, or a global-optimality guarantee.

The Hybrid frontend remains signature-only by default. With lower_body=True, it can statically capture allowlisted declarations and lower them into native programs; it never executes the decorated function or evaluates arbitrary Python. The subset excludes assignment, return values, conditionals, pattern matching, loops, exception handling, context managers, imports, lambdas, comprehensions, arbitrary attributes, and arbitrary callables. Source capture may be unavailable in REPL, standard-input, generated, or dynamically executed code; use the native Builder APIs there. Analog body lowering is global-only, requires an explicit register, permits exactly one drive and terminal measurement, and does not support local control or batch execution.

Every static LocalExecutionPlan still reports execution_ready=False because payload binding belongs to HybridProgram and the execution builder. A typed HybridProgram is executable through LocalBackend.run(); HybridProgramIR and plans are not direct Backend inputs. Ideal scan size and worker count are resource-driven. Strict fail-fast remains serial for truthful not_run states; continue-on-error uses bounded parallel batches. With store=, completed children are persisted and reused during local recovery; without a store, scans remain process-local.

Persistent execution is local-only. SQLite coordinates one active claim on one host, not a distributed scheduler or cross-host exactly-once system. Attempt timeout is cooperative evidence and cannot forcibly terminate NumPy, SciPy, or native code. History does not read Result bodies, Jobs do not expire automatically, and there is no prune API; retain or remove the SQLite file and its matching artifact directory together.

LocalBackend uses resource-driven planning and does not publish a fixed site maximum. Apple M4 acceptance points cover 24-qubit Digital, 18-site ideal Analog/Hybrid, 10-site exact density dephasing, and 16-site/256-trajectory noisy Hybrid workloads. LocalBackend(kernel_threads=N) can split the ideal fixed-step Krylov matrix-vector kernel across a bounded CPU thread pool, but it is rejected for scans and noisy execution. Continuous Hybrid multi-start optimization can run independent starts with parallel_workers; this requires an in-memory Backend and cannot be combined with kernel threading. Process workers are limited by effective CPU and available memory, use spawn-safe execution on macOS and Windows, and do not parallelize one optimizer start. These controls are local CPU optimizations, not distributed execution or performance guarantees for every program shape or host.

QAOA and VQE run locally and synchronously. Standalone and Unified Digital routes support ideal objectives and deterministic exact-density noisy objectives. VQE can also estimate finite-shot QWC energies and complete parameter-shift gradients under ideal execution or preparation, gate, idle, crosstalk, and readout noise; noisy sampled execution supports auto, density-matrix, and trajectory planning. Standalone and Unified Problem Digital VQE pass this estimator to native SPSA or Adam and may independently confirm candidates before final sampling. Every QWC group, confirmation, layer experiment, and final-sampling Job retains the run-level NoiseModel and SimulationOptions, while each Job keeps its own seed, counts, plan, noise report, and identity. Caller-supplied per-qubit calibration enables tensor-product linear-inverse readout mitigation without replacing raw integer counts; calibration is never inferred from NoiseModel. SPSA supports multiple directions and fixed or bounded standard-error-driven objective repeats. Adam supports fixed or bounded adaptive complete-gradient repeats, QWC-level pooling, and optional update-size plus gradient-uncertainty stopping. Objective evaluations, confirmation, shots, group Jobs, gradient callbacks, shift Jobs, optimizer updates, trajectories, and final sampling remain separate cost records. The runtime does not provide chemistry integral or fermion mappings, dense-matrix Hamiltonians, general automatic differentiation, trajectory exact objectives, sampled optimizers beyond SPSA and Adam, per-occurrence adaptive gradients, automatic readout-calibration acquisition, parallel SPSA directions or parameter shifts, broader error mitigation, Analog/Hybrid noisy optimization, distributed execution, persistent optimizer history, or a global-optimality guarantee. A local NoiseModel is a numerical model, not evidence that the run matches a physical device. Built-in hardware-efficient and fixed-cardinality VQE Definitions support automatic layer transfer; custom circuits remain fixed-depth. Fixed-cardinality VQE preserves only caller-declared group Hamming weights, does not infer business constraints, and may leave the subspace under noise. Exhaustive classical baselines are limited to 20 variables; this does not cap quantum simulation size.

VQE.benchmark_sampling() compares exact, single-sample, fixed-repeat, and adaptive-repeat SPSA under paired initial parameters, seeds, and an objective evaluation ceiling. Sampled strategies share QWC measurement and candidate confirmation, and every sampled-selected binding receives an independent exact check. The check separates estimator error from the paired exact-reference gap but does not prove a ground state, global optimum, or quantum advantage. Diagnostic exact Jobs are excluded from optimizer budgets and reported separately. The benchmark remains ideal Digital, local, synchronous, and SPSA-only.

VariationalResult.diagnose_stability() reads completed exact, ideal sampled, or noisy sampled native-SPSA VQE evidence. It checks each start separately and reports stable, unstable, or insufficient_evidence from configured terminal objective, update, gradient, and sampled-standard-error thresholds. A single sampled evaluation has no repeat standard error and is therefore insufficient. The diagnosis does not compensate for noise bias, change optimizer stopping, or prove a ground state, global optimum, strict convergence, or quantum advantage. SciPy optimizers and live results are not supported.

Native SPSA can instead use SPSAStoppingConfig during optimization. It checks complete pre-final iteration windows and may terminate with stability_reached; the final center still runs. Direction-standard-error stopping requires at least two directions, and sampled-standard-error stopping requires at least two repeats under ideal or noisy sampled execution. Configurations that cannot reach min_iterations fail before execution. Thresholds are not calibrated automatically, do not remove noise bias, and do not prove a ground state, global optimum, strict convergence, or quantum advantage. Direction parallelism and live hardware remain unsupported.

Native SPSA can calibrate only its learning-rate scale from complete initial-point directions. Fixed gain and calibrated gain are mutually exclusive. Calibration supports exact, exact-density, ideal sampled, and noisy sampled VQE, and its work enters objective and Backend budgets. It does not tune perturbation, schedule exponents, direction count, repeats, stopping thresholds, or Ansatz structure. A small local gradient fails at the configured floor instead of producing an unbounded gain. The resulting target update RMS is a local scale choice, not convergence or optimality evidence.

ProblemCompiler accepts digital + qaoa, digital + vqe, hybrid + qaoa, and analog + qaa. Built-in VQE Definitions support automatic layer transfer; custom VQE Circuits remain fixed-depth. Unified Digital VQE can run ideal or noisy finite-shot QWC objectives with native SPSA or Adam, optional readout mitigation, and fixed or sequential candidate confirmation. SPSA supports fixed or bounded adaptive objective repeats. Adam supports fixed or bounded adaptive complete-gradient repeats and optional uncertainty-aware stopping. Optimization, confirmation, and final-sampling costs remain separate. Sampled optimization does not support SciPy optimizers or parameter_sets.

ProblemCompiler.optimize_layers() runs one optimization at each contiguous Digital QAOA/VQE or Hybrid QAOA depth. Its sampled path is limited to ideal or noisy Digital VQE with SPSA or Adam, positive final shots, and independent candidate confirmation. Selection and layer transfer use confirmed energy and parameters. This remains a fixed-budget rule, not a statistical test. ProblemCompiler.optimize_layers_repeated() and standalone VQE.optimize_layers_repeated() require at least two complete optimizations per depth and select from paired Student-t lower-bound evidence. Sampled repeated VQE has the same confirmation requirement. Repeats are distinct from starts, shots, and trajectories. Repeated entries require optimizer.seed=None and derive each run seed from one root seed. No layer experiment supports Analog QAA, custom VQE, one fixed bounds tuple across changing dimensions, per-layer optimizer configs, global-optimality claims, adaptive repeat counts, bootstrap intervals, or multiple-comparison correction.

Hybrid accepts any positive QAOA depth and emits D-(A-D)^p-measure; each layer requires a non-empty Analog contribution and a strictly positive gamma. Analog succeeds only when the selected Target can express the complete Hamiltonian within tolerance. Local reference mapping does not establish production placement, calibration, scheduling, or hardware executability. Small-sample confidence statements cover only the stored local runs under one configuration. Problem comparison does not normalize unequal optimizer budgets, shots, host load, or route-specific resource units. Optimization still lacks persistent history and distributed execution.

When sampled_selection is enabled, the runtime independently confirms a fixed set of distinct optimizer points and selects the lowest confirmation mean. A larger max_repeats_per_candidate enables sequential looks for the current lowest-mean candidate and the challenger with the lowest confidence lower bound on their energy difference. The process stops on corrected confidence separation, the repeat ceiling, or the confirmation Backend budget. best_evaluation still identifies the lowest pooled optimization estimate; selected_evaluation identifies the final-sampling source. A separated or inconclusive status describes only the saved candidates under the configured normal approximation. Confirmation does not alter optimizer repeat decisions, enter optimizer nfev, or establish global optimality or quantum advantage.

The standalone repeated VQE report uses the lowest-objective repeat at the selected layer for its detailed lifecycle panels. This presentation choice does not change the statistical selection rule or discard the other runs from the report.

Current hardware and cloud related code paths are public contracts plus a repository-only offline mock. The mock Compiler Service/Gateway does not enter the public wheel or source distribution, and its counts are deterministic fixtures rather than simulation or hardware measurements. None of these paths is live execution.

Pulser is isolated in the reference-pulser optional extra. Default imports, tests, and examples do not load the third-party runtime. PulserReferenceBackend reuses the common lazy Job shape but supports exact single-site Analog results only; it is not a Hybrid or scan Backend. The actual reference gate is local and synchronous, and its benchmark reports machine-specific phase medians without a performance ratio claim. See Pulser Reference Validation.

When evaluating readiness for hardware or cloud integration, treat the current APIs as preparation surfaces. They help shape payloads, diagnostics, manifests, and result contracts, but they do not prove live service compatibility.

ProgramIR, ResultIR, and the source records retained by ProblemExecutionContextIR remain the source of truth. Visualization metadata, reports, result views, and readiness summaries are derived views.

For common local setup, example output, diagnostics, and boundary questions, see docs/user-guide/troubleshooting.md.

SDK 1.0.8a · `8b227bff`