---
title: Sampler quickstart
description: A quickstart guide on how to use the IBM Quantum Sampler primitive.
source: https://quantum.cloud.ibm.com/docs/en/ibm-quantum-compute/get-started-with-sampler
---

# Sampler quickstart

The Sampler's core task is sampling the output register from the execution of one or more quantum circuits. [Dynamic circuits](/docs/ibm-quantum-compute/execute-dynamic-circuits) and parameterized circuits are accepted as input (if parametrized circuits are submitted, the parameter values must also be provided). Sampler also supports built-in dynamical decoupling and twirling for [error suppression](/docs/guides/error-mitigation-and-suppression-techniques).

The steps in this topic describe how to set up Sampler, explore the options you can use to configure it, and invoke it in a program.

> **New Sampler implementation**
>
> New implementations of the Qiskit SamplerV2 and EstimatorV2 interfaces were introduced in qiskit-ibm-runtime v0.50.0. These client-side primitives perform most of the pre- and post-processing on the client side and delegate execution to the Executor primitive. Running on the client side provides greater transparency, faster debugging feedback, and finer control.
>
> Because they implement the same API, these client-side primitives are largely drop-in replacements of the legacy server-side primitives, with the only change being the import statement. See [Migrate from server-side to client-side Sampler and Estimator](/docs/guides/migrate-to-client-side-primitives) for more information.

### Package versions

The code on this page was developed using the following requirements.
We recommend using these versions or newer.

```
qiskit[all]~=2.5.2
qiskit-ibm-runtime~=0.47.0
```

## Steps to use the Sampler primitive

### 1. Initialize the account

You first need to initialize your account. You can then select the QPU you want to use.

Follow the steps in the [Set up your IBM Cloud account](/docs/guides/cloud-setup) topic if you don't already have an account set up.

> **Fractional gates**
>
> To use the newly supported [fractional gates](/docs/ibm-quantum-compute/fractional-gates), set `use_fractional_gates=True` when requesting a backend from a `QiskitRuntimeService` instance. For example:
>
> ```python
> service = QiskitRuntimeService()
> fractional_gate_backend = service.least_busy(use_fractional_gates=True)
> ```
>
> This is an experimental feature and might change in the future.

```python
from qiskit_ibm_runtime import QiskitRuntimeService

service = QiskitRuntimeService()
backend = service.least_busy(
    operational=True, simulator=False, min_num_qubits=127
)
```

### 2. Create a circuit

You need at least one circuit as the input to the Sampler primitive.

```python
import numpy as np
from qiskit.circuit.library import efficient_su2

circuit = efficient_su2(127, entanglement="linear")
circuit.measure_all()
# The circuit is parametrized, so we will define the parameter values for execution
param_values = np.random.rand(circuit.num_parameters)
```

The circuit and observable need to be transformed to only use instructions supported by the QPU (referred to as *instruction set architecture (ISA)* circuits). Use the transpiler to do this.

```python
from qiskit.transpiler import generate_preset_pass_manager

pm = generate_preset_pass_manager(optimization_level=1, backend=backend)
isa_circuit = pm.run(circuit)
print(f">>> Circuit ops (ISA): {isa_circuit.count_ops()}")
```

Output:

```
>>> Circuit ops (ISA): OrderedDict([('rz', 3036), ('sx', 1769), ('cz', 378), ('measure', 127), ('barrier', 1)])
```

### 3. Initialize the IBM Quantum Sampler

When you initialize Sampler, use the `mode` parameter to specify the mode you want it to run in.  Possible values are `batch`, `session`, or `backend` objects for batch, session, and job execution mode, respectively. For more information, see [Introduction to IBM Quantum Compute Service execution modes](/docs/ibm-quantum-compute/execution-modes). Note that Open Plan users cannot submit session jobs.

```python
# Legacy server-side primitive before qiskit-ibm-runtime 0.50.0
# from qiskit_ibm_runtime import Sampler

# Client-side primitive introduced in qiskit-ibm-runtime 0.50.0
from qiskit_ibm_runtime.executor_sampler import Sampler

sampler = Sampler(mode=backend)
```

### 4. Invoke Sampler and get results

Next, invoke the `run()` method to generate the output. The circuit and optional parameter value sets are input as *primitive unified bloc* (PUB) tuples.

```python
job = sampler.run([(isa_circuit, param_values)])
print(f">>> Job ID: {job.job_id()}")
print(f">>> Job Status: {job.status()}")
```

Output:

```
>>> Job ID: dab7lb6rrl7c7386gjgg
```

```
>>> Job Status: QUEUED
```

```python
result = job.result()

# Get results for the first (and only) PUB
pub_result = result[0]
print(
    f"First ten results for the 'meas' output register: "
    f"{pub_result.data.meas.get_bitstrings()[:10]}"
)
```

Output:

```
First ten results for the 'meas' output register: ['1110001000100100100111011000001001000101010000001100010010110011001100110111100000000110001000011001101000110100101110101010011', '1110101100010101010001010111111011000110011010100101001100110101010010101010101110001010100100000000011110101101011000100000100', '1100110011101000110000000100110111101010110001100010111100001101100001010100111001101010101110000101010001001101010101001000100', '1011001001011000000101010111111010011101001111010100001011110011000101110101011001100110011011110011101010000111001111110110011', '1110111011011111101011110101110101010110011001100110101111100100011101100011011100101100101001001111110101111010101110111111011', '0101001110001110010001010100010111011001000000011110000000000001110000010010101101011001000100000001011011101111010010110111110', '1101101001000100010000110001000101010010101011000011000011001010000111100110010101010110100110011010101100001011100110001111011', '1000110011111111100010101010101111001001100001110111101001100111010101010111110110011000110011010010010000100000100010010010101', '0101010100110011110011010000000100011001111100101100101100101111101110100001101101111010100011011000010011111010001100110000010', '0010000111011100000000110000001110001100010011000100101110111111100011001100011001101010011111111100000000011100101101111010100']
```

## Next steps

> **Recommendations**
>
> - Learn how to [test locally](/docs/ibm-quantum-compute/local-testing-mode) before running on quantum computers.
> - Review detailed [examples](/docs/ibm-quantum-compute/sampler-examples).
> - Practice with primitives by working through the [Cost function lesson](/learning/courses/variational-algorithm-design/cost-functions) in IBM Quantum Learning.
> - Learn how to transpile locally in the [Transpile](/docs/qiskit/transpile) section.
> - Try the [Compare transpiler settings](/docs/qiskit/circuit-transpilation-settings#compare-transpiler-settings) guide.
> - Learn how to [use the primitive options](/docs/ibm-quantum-compute/runtime-options-overview).
> - View the API for [Sampler](/docs/api/qiskit-ibm-runtime/options-models-sampler-options) options.