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

Start with simulators: Test locally before using hardware

from qiskit.primitives import StatevectorSampler
sampler = StatevectorSampler()

Always transpile: Optimize circuits before execution

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

Use appropriate primitives:
- Sampler for bitstrings (optimization algorithms)
- Estimator for expectation values (chemistry, physics)
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.

About this skill

Overview

When to Use This Skill

Does NOT Trigger

Quick Start

Installation

First Circuit

Visualization

Core Capabilities

1. Setup and Installation

2. Building Quantum Circuits

3. Primitives (Sampler and Estimator)

4. Transpilation and Optimization

5. Visualization

6. Hardware Backends

7. Qiskit Patterns Workflow

8. Quantum Algorithms and Applications

Workflow Decision Guide

Best Practices

Development Workflow

Performance Optimization

Hardware Execution

Common Patterns

Pattern 1: Simple Circuit Execution

Pattern 2: Hardware Execution with Transpilation

Pattern 3: Variational Algorithm (VQE)

Additional Resources