Skip to content

Observable Batching

中文版本

Use an ObservableSet to evaluate several Pauli observables from one final state or trajectory batch:

from cascaqit import LocalBackend, ObservableSet, PauliZ, PauliZZ

observables = ObservableSet([PauliZ("q0"), PauliZZ("q0", "q1")])
result = LocalBackend().run(program, observables=observables).result()
batch = result.observable_batch

Declaration order is preserved, and names must be unique within a set. PauliI, PauliX, PauliY, PauliZ, and PauliZZ cover common terms; use PauliProduct for ordered products such as XX or XYZ. Target names follow the program's logical order, normally q0, q1, and so on.

The backend does not rerun the program for each Observable. Every item in a batch is evaluated from the same final source and therefore shares its source_kind and source_hash. A parameter sweep gives each successful child result its own batch.

Read the Batch

Each item reports:

  • expectation: mean value of the Pauli Observable.
  • variance: quantum measurement variance, not estimator uncertainty.
  • standard_error: uncertainty of a trajectory or shot mean; zero for exact state and density evaluation.
  • sample_count: trajectory or shot count for a statistical estimator; unset for exact evaluation.
  • source_kind, source_hash, and estimator_kind: the state source and calculation semantics.
Source Estimator Meaning
State vector or subspace exact_state Exact expectation and variance; no sampling error.
Density matrix exact_density Exact trace evaluation; no sampling error.
Trajectory batch trajectory_mean Mean and standard error over the trajectories used by the noisy run.
Z-basis samples sample_mean I/Z products only; requires at least two shots.

Noise and Sweeps

Pass observables together with noise, options, or sweep. For example, a trajectory run reuses the same trajectories for Observable estimates:

result = LocalBackend().run(
    hybrid_program,
    noise=noise_model,
    observables=observables,
    options=SimulationOptions(method="trajectory", trajectories=256),
).result()

For a sweep, read item.result.observable_batch on each successful item. The aggregate scan result does not invent a merged final-state batch.

Limits

  • ObservableSet terms are coefficient-one Pauli products evaluated from one direct state, density, trajectory batch, or sample source. Weighted Hamiltonian measurement planning is a separate VQE path: VQE.evaluate_sampled() evaluates a standalone fixed parameter point, while standalone and Unified Problem sampled optimization reuse the same stable QWC grouping with explicit local basis rotations. Neither path supports general commuting-group diagonalization.
  • Evaluation uses the final state; mid-circuit capture is not available.
  • Sample evaluation rejects X/Y terms because Z-basis counts cannot determine them without a basis rotation.
  • A site removed by atom-loss noise cannot remain an Observable target; validation rejects the request before execution.
  • An Observable batch is derived from ResultIR. It does not replace the program, state, counts, or trajectory records.

Run python3 examples/user/observable_batch_workflow.py for Digital, Analog, Hybrid, noisy trajectory, and three-point sweep examples.

SDK 1.0.8a · `8b227bff`