Skip to main content
The calculate_state_vector(...) function is used when you want direct access to the quantum state itself, including amplitudes and phases. Related pages:

​
When to use state-vector calculation

Use calculate_state_vector(...) when you want the full quantum state rather than measurement statistics or a single expectation value.
State-vector calculations are only available only on Classiq simulators.
This is useful when you want to:
  • inspect amplitudes directly
  • understand the exact state prepared by the circuit
  • analyze phases and probabilities
  • debug or study a circuit without sampling noise
Unlike sampling, noiseless state-vector calculation is deterministic. It does not rely on repeated measurements, so it does not introduce statistical fluctuations.

​
Basic example

from classiq import *

backend_name = "simulator"

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

qprog = synthesize(main)

df = calculate_state_vector(
    qprog,
    backend=backend_name,
)
df
Example output
xamplitudemagnitudephaseprobabilitybitstring
00.707107+0.000000j0.710.00π0.50
10.707107+0.000000j0.710.00π0.51

​
Understanding the result

The returned object is a DataFrame describing the full state. Common columns include:
  • quantum variables - the quantum number values, quantum arrays, and qubits
  • amplitude — the complex amplitude of the basis state
  • magnitude — the absolute value of the amplitude
  • phase — the phase angle
  • probability — the squared magnitude
  • bitstring — the computational basis state
Because the result is a DataFrame, you can inspect or manipulate it using standard operations.

​
Filtering small amplitudes

By default, very small amplitudes are filtered out below a threshold of 10−1610^{-16}. You can control this behavior using amplitude_threshold: 
df = calculate_state_vector(
    qprog,
    backend=backend_name,
    amplitude_threshold=0.01
)
This is useful for reducing numerical noise and simplifying the displayed state, especially for larger systems where many amplitudes may be negligible.

​
Parameterized execution

State-vector calculation also supports parameterized quantum programs. This means you can define symbolic parameters in your circuit and provide their numerical values at execution time. Example 
from classiq import *

backend_name = "simulator"

@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)

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

df = calculate_state_vector(
    qprog,
    backend=backend_name,
    parameters=exec_params,
)
df
xamplitudemagnitudephaseprobabilitybitstring
10.779815+0.146834j0.790.06π0.6296721
00.575048-0.199119j0.61-0.11π0.3703280
In this workflow:
  • the circuit structure stays the same
  • the parameter values are supplied at execution time
  • the returned DataFrame describes the exact state corresponding to those values

​
Summary

Use calculate_state_vector(...) when you need the full quantum state. State-vector calculation:
  • returns a DataFrame
  • provides amplitudes, phases, and probabilities
  • is deterministic
  • supports parameterized execution
  • only allowed on simulators