observe

Expected value of quantum circuit or state

Since R2024b

Syntax

ev = observe(q)

ev = observe(q,o)

ev = observe(___,Name=Value)

Description

Add-On Required: This feature requires the MATLAB Support Package for Quantum Computing add-on.

ev = observe(q) returns the expected value of the specified quantum circuit or state.

ev = observe(q,o) returns the expected value of the quantum circuit or state in the basis specified by the observable o.

ev = observe(___,Name=Value) specifies options using one or more name-value arguments in addition to any of the input argument combinations in previous syntaxes. For example, to sample the circuit 100 times, set NumShots to 100.

Examples

Calculate Expected Value of Quantum Circuit

Create a quantum circuit with one $x$-axis rotation gate that acts on a single qubit with rotation angle pi/4.

gates = rxGate(1,pi/4);
c = quantumCircuit(gates);

Calculate the expected value of the quantum circuit. With no specified observable, the observe function defaults to a $Z$ basis measurement on each qubit with a weight of 1.

ev = observe(c)

ev = 
0.7071

Calculate Expected Value Using Observable

Create a quantum circuit with one $x$-axis rotation gate that acts on a single qubit with rotation angle pi/4. Create an observable where the $Y$ basis measurement is observed with a weight of 0.5 and the $Z$ basis measurement is observed with a weight of 1.

gates = rxGate(1,pi/4);
c = quantumCircuit(gates);
o = observable(["Y" "Z"],[0.5 1]);

Calculate the expected value of the quantum circuit in the basis specified by the observable.

ev = observe(c,o)

ev = 
0.3536

Specify Probability Threshold

Create the $|+⟩$ quantum state, which has a 0.5 probability of measuring either the $|1⟩$ state or the $|0⟩$ state, and calculate its expected value. Note that the expected value for states $|1⟩$ and $|0⟩$ are –1 and 1, respectively.

s = quantum.gate.QuantumState("+");
ev = observe(s)

ev = 
0

Calculate the expected value of the $|+⟩$ quantum state at the probability thresholds 0.45, 0.55, 0.8, and 0.95.

For probability threshold 0.45, which is less than the probability of measuring either state $|1⟩$ or $|0⟩$, the returned expected value is the lowest expected value of either state, which is -1.

ev45 = observe(s,ProbabilityThreshold=0.45)

ev45 = 
-1

For probability thresholds greater than the probability of measuring either state $|1⟩$ or $|0⟩$, 0.5, the returned expected value approaches the exact expected value of 0 as more of the probability distribution is included.

ev55 = observe(s,ProbabilityThreshold=0.55)

ev55 = 
-0.8182

ev80 = observe(s,ProbabilityThreshold=0.8)

ev80 = 
-0.2500

ev95 = observe(s,ProbabilityThreshold=0.95)

ev95 = 
-0.0526

Specify Number of Times to Sample Circuit

Create the $|+⟩$ quantum state, which has a 0.5 probability of measuring either the $|1⟩$ state or the $|0⟩$ state, and calculate its expected value. Note that the expected value for states $|1⟩$ and $|0⟩$ are –1 and 1, respectively.

s = quantum.gate.QuantumState("+");
ev = observe(s)

ev = 
0

Calculate the expected value of the $|+⟩$ quantum state by sampling the circuit 1, 100, and 10,000 times. As the number of samples increases, the expected value approaches the exact expected value of 0.

ev1 = observe(s,NumShots=1)

ev1 = 
-1

ev100 = observe(s,NumShots=100)

ev100 = 
-0.0600

ev10000 = observe(s,NumShots=10000)

ev10000 = 
-0.0068

Input Arguments

q — Quantum circuit or state

quantumCircuit object | quantum.gate.QuantumState object | vector of quantumCircuit objects | vector of quantum.gate.QuantumState objects

Quantum circuit or state, specified as a quantumCircuit object, quantum.gate.QuantumState object, vector of quantumCircuit objects, or vector of quantum.gate.QuantumState objects.

o — Observable

observable object | square matrix | vector of observable objects | vector of square matrices

Observable, specified as an observable object, a square Hermitian matrix, or a vector of observable objects or square Hermitian matrices. Use this argument to specify the possible Pauli basis measurement results of running the input quantum circuit or state. If you specify the observable, the function returns the expected value in the specified basis. If you do not specify an observable, the function defaults to a Z basis measurement on each qubit with a weight of 1.

Name-Value Arguments

Specify optional pairs of arguments as Name1=Value1,...,NameN=ValueN, where Name is the argument name and Value is the corresponding value. Name-value arguments must appear after other arguments, but the order of the pairs does not matter.

Example: ev = observe(s,ProbabilityThreshold=0.4)

NumShots — Number of times to sample circuit

positive integer scalar

Number of times to sample the circuit, specified as a positive integer scalar.

The function uses random sampling when you specify NumShots, so if you specify the number of times to sample the circuit, the result is an approximation of the exact expected value.

ProbabilityThreshold — Probability threshold

numeric scalar in range (0,1]

Probability threshold, specified as a numeric scalar in the range (0,1]. If you specify the probability threshold, the function returns the sum of the lowest expected values up to the total specified probability. You can specify the probability threshold only when the observable Pauli operator has a combination of I and Z basis measurements.

If you specify the probability threshold, the result is an approximation of the exact expected value.

Output Arguments

ev — Expected value

real numeric scalar | real numeric vector

Expected value, returned as a real numeric scalar or vector. The expected value is represented as the matrix-vector product s'*O*s, where s is the state vector and O is the matrix representation of the observable.

Tips

• The expected value represents the average measurement result and is fundamental to many quantum algorithms. You can use the observe function to compute exact or approximate expected values.

References

[1] Beeumen, Roel Van, Daan Camps, and Neil Mehta. “QCLAB++: Simulating Quantum Circuits on GPUs.” Preprint, submitted February 28, 2023. https://doi.org/10.48550/arXiv.2303.00123.

Version History

Introduced in R2024b

R2025b: Specify quantum circuits, states, and observables as vectors (November 2025, Version 25.2.1)

This function now supports implicit expansion. You can calculate the expected value of multiple quantum circuits or states at a time by specifying an input vector of quantumCircuit objects or quantum.gate.QuantumState objects. You can also specify a second input vector of observable objects.