Skip to main contentIBM Quantum Documentation


qiskit.primitives.StatevectorSampler(*, default_shots=1024, seed=None)

GitHub(opens in a new tab)

Bases: BaseSamplerV2

Simple implementation of BaseSamplerV2 using full state vector simulation.

This class is implemented via Statevector which turns provided circuits into pure state vectors, and is therefore incompatible with mid-circuit measurements (although other implementations may be).

As seen in the example below, this sampler supports providing arrays of parameter value sets to bind against a single circuit.

Each tuple of (circuit, <optional> parameter values, <optional> shots), called a sampler primitive unified bloc (PUB), produces its own array-valued result. The run() method can be given many pubs at once.

from qiskit.circuit import (
    Parameter, QuantumCircuit, ClassicalRegister, QuantumRegister
from qiskit.primitives import StatevectorSampler
import matplotlib.pyplot as plt
import numpy as np
# Define our circuit registers, including classical registers
# called 'alpha' and 'beta'.
qreg = QuantumRegister(3)
alpha = ClassicalRegister(2, "alpha")
beta = ClassicalRegister(1, "beta")
# Define a quantum circuit with two parameters.
circuit = QuantumCircuit(qreg, alpha, beta)
circuit.h(0), 1), 2)
circuit.ry(Parameter("a"), 0)
circuit.rz(Parameter("b"), 0), 2), 1)
circuit.measure([0, 1], alpha)
circuit.measure([2], beta)
# Define a sweep over parameter values, where the second axis is over.
# the two parameters in the circuit.
params = np.vstack([
    np.linspace(-np.pi, np.pi, 100),
    np.linspace(-4 * np.pi, 4 * np.pi, 100)
# Instantiate a new statevector simulation based sampler object.
sampler = StatevectorSampler()
# Start a job that will return shots for all 100 parameter value sets.
pub = (circuit, params)
job =[pub], shots=256)
# Extract the result for the 0th pub (this example only has one pub).
result = job.result()[0]
# There is one BitArray object for each ClassicalRegister in the
# circuit. Here, we can see that the BitArray for alpha contains data
# for all 100 sweep points, and that it is indeed storing data for 2
# bits over 256 shots.
assert == (100,)
assert == 2
assert == 256
# We can work directly with a binary array in performant applications.
raw =
# For small registers where it is anticipated to have many counts
# associated with the same bitstrings, we can turn the data from,
# for example, the 22nd sweep index into a dictionary of counts.
counts =
# Or, convert into a list of bitstrings that preserve shot order.
bitstrings =


  • default_shots (int(opens in a new tab)) – The default shots for the sampler if not specified during run.
  • seed (np.random.Generator | int(opens in a new tab) | None) – The seed or Generator object for random number generation. If None, a random seeded default RNG will be used.



Return the default shots


Return the seed or Generator object for random number generation.



run(pubs, *, shots=None)

GitHub(opens in a new tab)

Run and collect samples from each pub.


  • pubs (Iterable[SamplerPubLike]) – An iterable of pub-like objects. For example, a list of circuits or tuples (circuit, parameter_values).
  • shots (int(opens in a new tab) | None) – The total number of shots to sample for each sampler pub that does not specify its own shots. If None, the primitive’s default shots value will be used, which can vary by implementation.


The job object of Sampler’s result.

Return type


Was this page helpful?
Report a bug or request content on GitHub.