Hello World: Your First Quantum Circuit

Build a Bell state (two entangled qubits) and run it three ways:

1. Ideal simulation — perfect results, no account needed
2. Noisy simulation — simulates a real device, no account needed
3. Real quantum hardware — requires a free IBM Quantum account (setup steps below)

Build the circuit

# Added by doQumentation — required packages for this notebook
!pip install -q qiskit qiskit-ibm-runtime

from qiskit import QuantumCircuit

qc = QuantumCircuit(2)
qc.h(0)
qc.cx(0, 1)
qc.measure_all()

qc.draw(output="mpl")

Option 1: Ideal simulation (no account needed)

Uses StatevectorSampler — a local simulator with perfect, noise-free results.

from qiskit.primitives import StatevectorSampler

result = StatevectorSampler().run([qc], shots=1024).result()
counts = result[0].data.meas.get_counts()
counts

from qiskit.visualization import plot_histogram
plot_histogram(counts)

Option 2: Noisy simulation (no account needed)

Uses FakeManilaV2 — a local simulator that mimics a real IBM quantum device, including its noise characteristics. The circuit must first be transpiled (adapted) to the device's gate set and qubit connectivity.

from qiskit_ibm_runtime import SamplerV2
from qiskit_ibm_runtime.fake_provider import FakeManilaV2
from qiskit.transpiler.preset_passmanagers import generate_preset_pass_manager

backend = FakeManilaV2()
pm = generate_preset_pass_manager(backend=backend, optimization_level=1)
isa_qc = pm.run(qc)

result = SamplerV2(mode=backend).run([isa_qc], shots=1024).result()
counts = result[0].data.meas.get_counts()
counts

plot_histogram(counts)

Option 3: Real quantum hardware

Requires a free IBM Quantum account. To set one up:

1. Register at quantum.cloud.ibm.com/registration — no credit card required for the first 30 days
2. Sign in at quantum.cloud.ibm.com and select region us-east (required for the free Open Plan)
3. Create an instance (free Open Plan) at Instances if you don't have one yet
4. Create an API key at quantum.cloud.ibm.com (or at cloud.ibm.com/iam/apikeys)
5. Copy your CRN (Cloud Resource Name) from your Instances page

Then, if you haven't saved your credentials yet in this Binder session, run the cell below. Replace <your-api-key> with the API key from step 4, and <your-crn> with the CRN from step 5.

from qiskit_ibm_runtime import QiskitRuntimeService

QiskitRuntimeService.save_account(
    channel="ibm_quantum_platform",
    token="<your-api-key>",
    instance="<your-crn>",
    set_as_default=True,
    overwrite=True,
)

Note: Jobs on real hardware may take some time depending on queue times. If the cell is still running, you can check your job status and see the results at quantum.cloud.ibm.com/workloads.

from qiskit_ibm_runtime import QiskitRuntimeService, SamplerV2
from qiskit.transpiler.preset_passmanagers import generate_preset_pass_manager

service = QiskitRuntimeService()
backend = service.least_busy(operational=True, simulator=False)
print(f"Running on {backend.name}")

pm = generate_preset_pass_manager(backend=backend, optimization_level=1)
isa_qc = pm.run(qc)

result = SamplerV2(mode=backend).run([isa_qc], shots=1024).result()
counts = result[0].data.meas.get_counts()
counts

plot_histogram(counts)

What next?

• Tutorials — step-by-step guides on algorithms, error mitigation, transpilation, and more
• Guides — reference material on running circuits, primitives, and the Qiskit Runtime
• Courses — structured learning paths from quantum basics to utility-scale computing
• Modules — deeper conceptual modules in computer science and quantum mechanics