Observe

The observe(...) workflow is used when you want expectation values of one or more observables rather than a full measurement distribution or the complete state vector. Related pages:

When to use observe

Use observe(...) when your goal is to compute expectation values of observables with respect to the executed quantum state. This is especially useful in workflows such as:

variational algorithms
optimization loops
cost-function evaluation
repeated evaluation of the same circuit under different parameter values

Unlike sampling, which returns a distribution of measurement outcomes, observe(...) returns expectation values (a scalar for a single observable, or lists when batching observables and/or parameter sets). Unlike state-vector calculation, it does not expose the full quantum state.

Basic example

from classiq import *

@qfunc
def main(res: Output[QBit]) -> None:
    allocate(res)
    H(res)

qprog = synthesize(main)

# Define your observable using SparsePauliOp
my_observable = Pauli.Z(0) - Pauli.Y(0)

value = observe(
    qprog,
    observables=my_observable,
    num_shots=1000,
)

value

Output:-0.013999999999999999

Understanding the result

When you pass a single observable and a single parameter set, the returned value is a single scalar. It represents the expectation value of the observable with respect to the state produced by the circuit. In other words, it summarizes the behavior of the circuit relative to the operator you are interested in. This is useful when you care about one derived quantity rather than the full result space. When batching is used, return shapes are:

single observable + list of parameter sets -> list[float]
list of observables + single parameter set -> list[float]
list of observables + list of parameter sets -> list[list[float]], indexed as [observable_index][parameter_index]

Choosing execution settings

As with the other execution functions, you can configure the execution using standard arguments such as:

estimate
num_shots
parameters
run_via_classiq
verbose

For example:

value = observe(
    qprog,
    observables=my_observable,
    estimate=True,
    num_shots=2000,
    run_via_classiq=False,
    verbose=True,
)

Parameterized execution

Many practical uses of observe(...) involve parameterized circuits. Instead of fixing all values inside the circuit, you define symbolic parameters in the quantum function and provide their values when you execute the program.

Defining a parameterized quantum program

from classiq import *

@qfunc
def main(angle_rx: CReal, angle_ry: CReal, x: Output[QBit]):
    allocate(x)
    RX(angle_rx, x)
    H(x)
    RY(angle_ry, x)

qprog = synthesize(main)

Supplying parameter values

exec_params = {
    "angle_rx": 0.5,
    "angle_ry": 0.3
}

value = observe(
    qprog,
    observables=my_observable,
    parameters=exec_params,
    num_shots=1000,
)
value

Output:-0.748

This allows you to evaluate how the expectation value changes as the circuit parameters change.

Batch of expectation values (parameter sweep)

A common pattern is to evaluate the same observable for many parameter settings. Instead of calling observe(...) repeatedly, you can pass a list of parameter dictionaries. The function then returns a list of scalar values, one per parameter set. Example

rx_angles = [0.1, 0.2, 0.3, 0.4]

exec_params = [
    {"angle_rx": angle, "angle_ry": 0.3}
    for angle in rx_angles
]

values = observe(
    qprog,
    observables=my_observable,
    parameters=exec_params,
    num_shots=1000,
)

values

Output:[-0.396, -0.526, -0.6100000000000001, -0.642]

Understanding batch results

When parameters is a list:

the output is a list of scalar values
each value corresponds to one execution
the order matches the order of the provided parameter dictionaries

This makes observe(...) a natural fit for optimization and sweep-style workflows, where you want to evaluate the same quantity many times.

Batch of observables

You can also evaluate multiple observables in one call by passing a list in observable.

observables = [
    Pauli.Z(0),
    Pauli.X(0),
]

values = observe(
    qprog,
    observables=observables,
    parameters={"angle_rx": 0.5, "angle_ry": 0.3},
    num_shots=1000,
)

values

If you pass both a list of observables and a list of parameter dictionaries, the output is nested:

first index -> observable
second index -> parameter set

`observables` keyword and legacy `hamiltonian` support

For ExecutionSession.observe(...) and ExecutionSession.submit_observe(...), the canonical keyword is observables. The legacy hamiltonian keyword is still supported for backward compatibility (with a deprecation warning), so existing code continues to run during the transition period.

In ExecutionSession.observe(...), when both the observable input and parameters are lists, observables=... returns a nested list ([observable][parameter]). Calls that still use legacy hamiltonian=... keep the historical flat-list shape for backward compatibility.

Summary

Use observe(...) when you care about expectation values of one or more observables. Observe:

returns a scalar or list-shaped output, depending on input
is ideal for cost functions and iterative algorithms
supports both single and batch parameterized execution

AI

Authentication

Modeling

Synthesis

Execution

Analysis

Studio

Applications

When to use observe

Basic example

Understanding the result

Choosing execution settings

Parameterized execution

Defining a parameterized quantum program

Supplying parameter values

Batch of expectation values (parameter sweep)

Understanding batch results

Batch of observables

`observables` keyword and legacy `hamiltonian` support

Summary

​When to use observe

​Basic example

​Understanding the result

​Choosing execution settings

​Parameterized execution

​Defining a parameterized quantum program

​Supplying parameter values

​Batch of expectation values (parameter sweep)

​Understanding batch results

​Batch of observables

​observables keyword and legacy hamiltonian support

​Summary

When to use observe

Basic example

Understanding the result

Choosing execution settings

Parameterized execution

Defining a parameterized quantum program

Supplying parameter values

Batch of expectation values (parameter sweep)

Understanding batch results

Batch of observables

`observables` keyword and legacy `hamiltonian` support

Summary