alterlab-qiskit

name	alterlab-qiskit
description	Builds, transpiles, and runs quantum circuits with Qiskit, IBM's quantum computing framework, including Qiskit Runtime primitives (Sampler/Estimator), circuit transpilation, and error mitigation on IBM Quantum hardware. Use when targeting IBM Quantum backends, transpiling circuits, running Runtime sessions or batches, or applying resilience/error mitigation. For Google Quantum AI hardware and NISQ circuits prefer alterlab-cirq; for gradient-trained quantum ML and hybrid quantum-classical models prefer alterlab-pennylane; for open-system Lindblad/master-equation dynamics prefer alterlab-qutip. Part of the AlterLab Academic Skills suite.
license	Apache-2.0
allowed-tools	Read Write Edit Bash(python:*)
compatibility	No API key required for local simulation. Runs via `uv run python`; requires the qiskit Python package. IBM Quantum hardware/Runtime needs an IBM Quantum account and API token.
metadata	{"skill-author":"AlterLab","version":"1.0.0"}

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 systems), IonQ, Amazon Braket, and other providers.

Version note: Examples target Qiskit SDK 2.x (qiskit>=2,<3, Python 3.10+) and qiskit-ibm-runtime 0.30+. Two breaking changes drive the patterns below: Qiskit 2.0 removed qiskit.pulse and Qiskit 1.0 removed qiskit.tools.jupyter, and the legacy qiskit_ibm_runtime.Options class plus the channel="ibm_quantum" value are both gone (use V2 options + channel="ibm_quantum_platform").

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() for testing
• 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 import transpile

service = QiskitRuntimeService()
backend = service.backend("ibm_brisbane")

qc_optimized = transpile(qc, backend=backend, optimization_level=3)

sampler = Sampler(backend)
job = sampler.run([qc_optimized], shots=1024)
result = job.result()

Pattern 3: Variational Algorithm (VQE)

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

with Session(backend=backend) as session:
    estimator = Estimator(session=session)

    def cost_function(params):
        bound_qc = ansatz.assign_parameters(params)
        qc_isa = transpile(bound_qc, backend=backend)
        result = estimator.run([(qc_isa, hamiltonian)]).result()
        return result[0].data.evs

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

Additional Resources

• Official Docs: https://quantum.ibm.com/docs
• Qiskit Textbook: https://qiskit.org/learn
• API Reference: https://docs.quantum.ibm.com/api/qiskit
• Patterns Guide: https://quantum.cloud.ibm.com/docs/en/guides/intro-to-patterns