alterlab-qiskit

Qiskit

Overview

Qiskit is an open-source quantum computing framework. Build quantum circuits, optimize for hardware, execute on simulators or real quantum computers, and analyze results. Supports IBM Quantum (100+ qubit Heron and Nighthawk systems), IonQ, Amazon Braket, and other providers.

Version note: Examples target Qiskit SDK 2.x (qiskit>=2,<3, Python 3.10+; current 2.5.x as of 2026-09) and qiskit-ibm-runtime ≥ 0.40 (current 0.49). Older tutorials break on these changes, so check any snippet you adapt against them:

• Qiskit 1.0 removed execute(), BasicAer, qiskit.tools (incl. tools.jupyter, job_monitor) and bind_parameters — use primitives, qiskit.providers.basic_provider.BasicSimulator, and assign_parameters.
• Qiskit 2.0 removed qiskit.pulse, BackendV1, the V1 reference primitives (qiskit.primitives.Sampler/Estimator) and Instruction.c_if (use with qc.if_test(...)).
• Qiskit 2.1 deprecated the class forms of library circuits (RealAmplitudes, EfficientSU2, TwoLocal, ZZFeatureMap, QFT, …; removal in 3.0) — use real_amplitudes(), efficient_su2(), n_local(), zz_feature_map(), QFTGate.
• Runtime V2 primitives take mode= (a backend, Session, or Batch); the old session=/backend= keywords raise TypeError. The Options class and channel="ibm_quantum" are gone — the platform is now quantum.cloud.ibm.com (API key + instance CRN, channel "ibm_quantum_platform").

When to Use This Skill

Use this skill when the user wants to:

• Build, transpile, and run gate-model circuits on IBM Quantum hardware or local simulators
• Use Qiskit Runtime primitives (SamplerV2 / EstimatorV2) in job, batch, or session mode
• Apply error suppression/mitigation (twirling, dynamical decoupling, TREX, ZNE)
• Run variational or textbook algorithms (VQE, QAOA, Grover, QPE) with the Qiskit ecosystem (Nature, Machine Learning, Optimization)

Does NOT Trigger

Scenario	Use Instead
Google Quantum AI processors, Cirq-native circuits, or XEB/RB characterization in Cirq	alterlab-cirq
Gradient-trained hybrid quantum-classical models with PyTorch/JAX autodiff	alterlab-pennylane
Open-system dynamics — Lindblad master equations, decoherence, cavity QED	alterlab-qutip
Classical quantum-chemistry (DFT, conformers, pKa) with no quantum circuits	alterlab-rowan

Key Features:

• Configurable transpilation with multiple optimization levels
• Circuit optimization that reduces two-qubit gate counts
• Backend-agnostic execution (local simulators or cloud hardware)
• Comprehensive algorithm libraries for optimization, chemistry, and ML

Quick Start

Installation

uv pip install "qiskit>=2,<3"
uv pip install "qiskit[visualization]" matplotlib   # circuit/result plotting
uv pip install qiskit-ibm-runtime                   # IBM hardware + Runtime primitives

First Circuit

from qiskit import QuantumCircuit
from qiskit.primitives import StatevectorSampler

# Create Bell state (entangled qubits)
qc = QuantumCircuit(2)
qc.h(0)           # Hadamard on qubit 0
qc.cx(0, 1)       # CNOT from qubit 0 to 1
qc.measure_all()  # Measure both qubits

# Run locally
sampler = StatevectorSampler()
result = sampler.run([qc], shots=1024).result()
counts = result[0].data.meas.get_counts()
print(counts)  # {'00': ~512, '11': ~512}

Visualization

from qiskit.visualization import plot_histogram

qc.draw('mpl')           # Circuit diagram
plot_histogram(counts)   # Results histogram

Core Capabilities

1. Setup and Installation

For detailed installation, authentication, and IBM Quantum account setup:

• See references/setup.md

Topics covered:

• Installation with uv
• Python environment setup
• IBM Quantum account and API token configuration
• Local vs. cloud execution

2. Building Quantum Circuits

For constructing quantum circuits with gates, measurements, and composition:

• See references/circuits.md

Topics covered:

• Creating circuits with QuantumCircuit
• Single-qubit gates (H, X, Y, Z, rotations, phase gates)
• Multi-qubit gates (CNOT, SWAP, Toffoli)
• Measurements and barriers
• Circuit composition and properties
• Parameterized circuits for variational algorithms

3. Primitives (Sampler and Estimator)

For executing quantum circuits and computing results:

• See references/primitives.md

Topics covered:

• Sampler: Get bitstring measurements and probability distributions
• Estimator: Compute expectation values of observables
• V2 interface (StatevectorSampler, StatevectorEstimator)
• IBM Quantum Runtime primitives for hardware
• Sessions and Batch modes
• Parameter binding

4. Transpilation and Optimization

For optimizing circuits and preparing for hardware execution:

• See references/transpilation.md

Topics covered:

• Why transpilation is necessary
• Optimization levels (0-3)
• Six transpilation stages (init, layout, routing, translation, optimization, scheduling)
• Advanced features (virtual permutation elision, gate cancellation)
• Common parameters (initial_layout, approximation_degree, seed)
• Best practices for efficient circuits

5. Visualization

For displaying circuits, results, and quantum states:

• See references/visualization.md

Topics covered:

• Circuit drawings (text, matplotlib, LaTeX)
• Result histograms
• Quantum state visualization (Bloch sphere, state city, QSphere)
• Backend topology and error maps
• Customization and styling
• Saving publication-quality figures

6. Hardware Backends

For running on simulators and real quantum computers:

• See references/backends.md

Topics covered:

• IBM Quantum backends and authentication
• Backend properties and status
• Running on real hardware with Runtime primitives
• Job management and queuing
• Session mode (iterative algorithms)
• Batch mode (parallel jobs)
• Local simulators (StatevectorSampler, Aer)
• Third-party providers (IonQ, Amazon Braket)
• Error mitigation strategies

7. Qiskit Patterns Workflow

For implementing the four-step quantum computing workflow:

• See references/patterns.md

Topics covered:

• Map: Translate problems to quantum circuits
• Optimize: Transpile for hardware
• Execute: Run with primitives
• Post-process: Extract and analyze results
• Complete VQE example
• Session vs. Batch execution
• Common workflow patterns

8. Quantum Algorithms and Applications

For implementing specific quantum algorithms:

• See references/algorithms.md

Topics covered:

• Optimization: VQE, QAOA, Grover's algorithm
• Chemistry: Molecular ground states, excited states, Hamiltonians
• Machine Learning: Quantum kernels, VQC, QNN
• Algorithm libraries: Qiskit Nature, Qiskit ML, Qiskit Optimization
• Physics simulations and benchmarking

Workflow Decision Guide

If you need to:

• Install Qiskit or set up IBM Quantum account → references/setup.md
• Build a new quantum circuit → references/circuits.md
• Understand gates and circuit operations → references/circuits.md
• Run circuits and get measurements → references/primitives.md
• Compute expectation values → references/primitives.md
• Optimize circuits for hardware → references/transpilation.md
• Visualize circuits or results → references/visualization.md
• Execute on IBM Quantum hardware → references/backends.md
• Connect to third-party providers → references/backends.md
• Implement end-to-end quantum workflow → references/patterns.md
• Build specific algorithm (VQE, QAOA, etc.) → references/algorithms.md
• Solve chemistry or optimization problems → references/algorithms.md

Best Practices

Development Workflow

1. Start with simulators: Test locally before using hardware

   from qiskit.primitives import StatevectorSampler
   sampler = StatevectorSampler()
   

2. Always transpile: Optimize circuits before execution

   from qiskit import transpile
   qc_optimized = transpile(qc, backend=backend, optimization_level=3)
   

3. Use appropriate primitives:

   • Sampler for bitstrings (optimization algorithms)
   • Estimator for expectation values (chemistry, physics)

4. Choose execution mode:

   • Session: Iterative algorithms (VQE, QAOA)
   • Batch: Independent parallel jobs
   • Single job: One-off experiments

Performance Optimization

• Use optimization_level=3 for production
• Minimize two-qubit gates (major error source)
• Test with noisy simulators before hardware
• Save and reuse transpiled circuits
• Monitor convergence in variational algorithms

Hardware Execution

• Check backend status before submitting
• Use least_busy() or list service.backends() rather than hard-coding a QPU name — QPUs are retired over time (all 127-qubit Eagle systems, e.g. ibm_brisbane, are gone)
• Session mode needs a paid plan; Open Plan users run in job or batch mode
• Save job IDs for later retrieval
• Apply error mitigation — resilience_level on the Estimator (Sampler has no resilience_level; use twirling / dynamical_decoupling)
• Start with fewer shots, increase for final runs

Common Patterns

Pattern 1: Simple Circuit Execution

from qiskit import QuantumCircuit, transpile
from qiskit.primitives import StatevectorSampler

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

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

Pattern 2: Hardware Execution with Transpilation

from qiskit_ibm_runtime import QiskitRuntimeService, SamplerV2 as Sampler
from qiskit.transpiler import generate_preset_pass_manager

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

# Hardware only accepts ISA circuits (native gates + connectivity)
pm = generate_preset_pass_manager(backend=backend, optimization_level=3)
qc_isa = pm.run(qc)

sampler = Sampler(mode=backend)          # job mode; pass a Session/Batch for other modes
job = sampler.run([qc_isa], shots=1024)
counts = job.result()[0].data.meas.get_counts()

Pattern 3: Variational Algorithm (VQE)

from qiskit_ibm_runtime import Session, EstimatorV2 as Estimator
from scipy.optimize import minimize

# Transpile once, then lay the observable out on the same physical qubits —
# an un-mapped observable does not match the ISA circuit's width.
ansatz_isa = pm.run(ansatz)
hamiltonian_isa = hamiltonian.apply_layout(ansatz_isa.layout)

with Session(backend=backend) as session:      # paid plans; use Batch on the Open Plan
    estimator = Estimator(mode=session)

    def cost_function(params):
        # parameter values travel in the PUB — no re-transpiling per iteration
        result = estimator.run([(ansatz_isa, hamiltonian_isa, params)]).result()
        return float(result[0].data.evs)

    result = minimize(cost_function, initial_params, method='COBYLA')

Additional Resources

• Official Docs: https://quantum.cloud.ibm.com/docs
• IBM Quantum Learning (successor to the Qiskit Textbook): https://quantum.cloud.ibm.com/learning
• API Reference: https://quantum.cloud.ibm.com/docs/en/api/qiskit
• Patterns Guide: https://quantum.cloud.ibm.com/docs/en/guides/intro-to-patterns
• Community packages: Nature, Machine Learning, Optimization

Part of the AlterLab Academic Skills suite.