Skip to content
Tutorials Center
My learning

Topics

Lesson 28 of 39 ยท Quantum Programming Tools

Qiskit Basics: Circuits, Samplers and Estimators

Learn the core of Qiskit: QuantumCircuit, Statevector, Sampler and Estimator primitives, transpilation and qubit ordering, with runnable NumPy stand-ins.

Qiskit is IBM's open-source Python SDK and the most widely used quantum programming framework. It lets you build circuits, simulate them, optimize ("transpile") them for a specific device and run them on real hardware. Everything you have built by hand with NumPy in this course maps directly onto Qiskit objects, so learning it is mostly learning names.

Qiskit cannot run on this site: it needs the qiskit package installed on your own computer (pip install qiskit qiskit-aer). The Qiskit blocks below are read-only. Next to each one is a small runnable stand-in written in plain NumPy, so you can see what the library computes, including its trickiest convention: the qubit order.

Install and first circuit

Terminal
python -m venv .venv
source .venv/bin/activate        # Windows: .venv\Scripts\activate
pip install qiskit qiskit-aer matplotlib

A circuit is a list of instructions on named qubits and classical bits. This one makes a Bell state:

Python
from qiskit import QuantumCircuit

qc = QuantumCircuit(2)
qc.h(0)            # Hadamard on qubit 0
qc.cx(0, 1)        # CNOT: control 0, target 1
qc.measure_all()   # add a classical register named "meas" and measure everything

print(qc.draw("text"))

Gates are methods: x, y, z, h, s, t, sdg, tdg, rx, ry, rz, p, u, cx, cz, swap, ccx, .... Parameterized gates take angles in radians. For circuits you want to reuse with different angles, use Parameter objects, which is the foundation for variational algorithms.

Looking at the exact state: Statevector

For small circuits you can ask for the ideal state without any measurement:

Python
from qiskit import QuantumCircuit
from qiskit.quantum_info import Statevector

qc = QuantumCircuit(2)
qc.h(0)
qc.cx(0, 1)
state = Statevector(qc)          # no measurements in the circuit!
print(state.probabilities_dict())   # {'00': 0.5, '11': 0.5}

The qubit-order trap

Qiskit is little-endian: qubit 0 is the rightmost bit of a bit string and the least significant bit of the basis-state index. So a circuit that flips only qubit 0 yields "01", not "10". Textbooks usually write the opposite (qubit 0 leftmost, as in this course's NumPy simulators). When comparing numbers between sources, check the convention first.

Here is a miniature, runnable stand-in with the same method names (h, x, cx, ry) and the same little-endian output:

Python A mini QuantumCircuit with Qiskit's bit order

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Running circuits: the primitives

Modern Qiskit does not run circuits with an old-style execute. It uses two primitives:

  • Sampler: runs a circuit with measurements and returns bit strings (counts). Use it when you need outcome distributions.
  • Estimator: returns the expectation value of an observable such as Z0 Z1, given a circuit with no measurements. It is the right tool for variational algorithms and chemistry.
Python
from qiskit import QuantumCircuit
from qiskit.primitives import StatevectorSampler, StatevectorEstimator
from qiskit.quantum_info import SparsePauliOp

bell = QuantumCircuit(2)
bell.h(0)
bell.cx(0, 1)

# Estimator: expectation values, no measurement gates
estimator = StatevectorEstimator()
obs = SparsePauliOp(["ZZ", "XX", "ZI"])
result = estimator.run([(bell, obs)]).result()
print(result[0].data.evs)            # [1. 1. 0.]

# Sampler: counts, circuit must be measured
bell.measure_all()
sampler = StatevectorSampler()
job = sampler.run([bell], shots=1000)
print(job.result()[0].data.meas.get_counts())   # e.g. {'00': 508, '11': 492}

StatevectorSampler and StatevectorEstimator are exact, local reference implementations. On real devices you replace them by SamplerV2 and EstimatorV2 from qiskit_ibm_runtime (see running on hardware); the code stays almost identical. For noisy simulation use qiskit_aer.

A runnable view of what the Estimator computes: the expectation <psi|P|psi> of a Pauli string, with the little-endian string order ("ZI" means Z on qubit 1 and I on qubit 0).

Python Estimator stand-in: expectation values of Pauli strings

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Transpilation

Real chips support only a small native gate set (for example sx, rz, cz or ecr) and a fixed coupling map that says which qubit pairs can interact. Transpiling rewrites your abstract circuit into one the device can run, which includes:

  1. Layout: choose which physical qubits stand for your circuit's qubits.
  2. Routing: insert SWAP gates so that two-qubit gates only act on connected qubits.
  3. Translation: decompose gates into the native set.
  4. Optimization: cancel redundant gates, merge rotations; levels 0 to 3 trade compile time against circuit quality.
Python
from qiskit import QuantumCircuit
from qiskit.transpiler.preset_passmanagers import generate_preset_pass_manager
from qiskit_aer import AerSimulator

backend = AerSimulator()                 # or a real backend object
pm = generate_preset_pass_manager(optimization_level=3, backend=backend)
isa_circuit = pm.run(bell)               # "ISA" = instruction set architecture circuit
print(isa_circuit.count_ops(), isa_circuit.depth())

Look at depth and the number of two-qubit gates after transpiling. On noisy hardware, those two numbers predict the result quality much better than the original circuit does, because of the (1 - epsilon)^G rule from noise and decoherence.

Useful tools in the ecosystem

  • qc.draw("mpl") draws a circuit diagram with Matplotlib; plot_histogram(counts) draws the outcome distribution.
  • qiskit.circuit.library contains ready-made blocks: QFT, GroverOperator, PhaseEstimation, ansatz families like EfficientSU2, and more.
  • qiskit.quantum_info offers Statevector, DensityMatrix, Operator, Pauli, SparsePauliOp, fidelity functions and noise channels.
  • Qiskit Aer gives fast simulators (state vector, density matrix, stabilizer, matrix product state) and noise models imported from real devices.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. In Qiskit, which bit of the output string corresponds to qubit 0?

    Qiskit uses little-endian ordering: qubit 0 is the least significant, rightmost bit.
  2. 2. Which primitive should you use to obtain the expectation value of an observable such as ZZ?

    The Estimator returns expectation values; the Sampler returns bit-string counts from measurements.
  3. 3. What does transpiling do?

    It performs layout, routing, gate translation and optimization for a specific backend.
  4. 4. Why does Statevector(qc) need a circuit without measurements?

    A measurement collapses the state randomly; the exact state vector only makes sense for unitary circuits.

Summary

  • Qiskit builds circuits as QuantumCircuit objects with gate methods; Statevector gives exact states for small circuits.
  • Use the Sampler for bit-string distributions and the Estimator for expectation values.
  • Qiskit is little-endian: qubit 0 is the rightmost bit.
  • Transpile for a backend before running; depth and two-qubit gate count drive real-device quality.

Next: Cirq, PennyLane and Other SDKs