Migrating QAOA from Qiskit 1.x to 2.x: An experience report

TL;DR

The paper investigates migrating QAOA from Qiskit 1.x to 2.x, revealing that surface-level algorithmic equivalence can mask deep gaps caused by sampling budgets and post-processing. Through a controlled reimplementation and systematic root-cause analysis, the authors identify the sampling budget as the dominant factor driving accuracy, with unlimited shots producing near-library-quality results and finite shots (e.g., 10k) yielding sparse sampling and poor optimization outcomes. They demonstrate monotonic accuracy gains as shots increase, ultimately nearing library performance at high budgets (250k shots), and they provide concrete recommendations for algorithm developers and framework designers to ensure reproducibility during migrations. The work highlights broader challenges in quantum software engineering, including explicit parameter exposure, end-to-end validation, and transparent migration practices that are essential for reliable quantum-classical hybrids on evolving platforms.

Abstract

Migrating quantum algorithms across evolving frameworks introduces subtle behavioral changes that affect accuracy and reproducibility. This paper reports our experience converting the Quantum Approximate Optimization Algorithm (QAOA) from Qiskit Algorithms with Qiskit 1.x (v1 primitives) to a custom implementation using Qiskit 2.x (v2 primitives). Despite identical circuits, optimizers, and Hamiltonians, the new version produced drastically different results. A systematic analysis revealed the root cause: the sampling budget -- the number of circuit executions (shots) per iteration. The library's implicit use of unlimited shots yielded dense probability distributions, whereas the v2 default of 10 000 shots captured only 23% of the state space. Increasing shots to 250 000 restored library-level accuracy. This study highlights how hidden parameters at the quantum-classical interaction level can dominate hybrid algorithm performance and provides actionable recommendations for developers and framework designers to ensure reproducible results in quantum software migration.

Figures (4)

• Figure 1: An example of a layered architecture.
• Figure 2: Conceptual flow of the QAOA-based hybrid process with explicit Post-processing. The Layered Architecture Recovery (LAR) problem is transformed into a QUBO, mapped to an Ising Hamiltonian, and optimized with QAOA. After quantum execution, bitstring samples are classically post-processed to select feasible and low-cost solutions before the optimizer updates $(\gamma,\beta)$ parameters.
• Figure 3: QAOA circuit with $p=2$ repetitions. The circuit prepares the superposition state $|+\rangle^{\otimes n}$ with Hadamard gates, alternates problem unitaries $U_C(\gamma_\ell)$ and mixer unitaries $U_M(\beta_\ell)$, and measures all qubits. A classical optimizer iteratively updates $(\gamma,\beta)$ to minimize the expected cost.
• Figure 4: Qiskit QAOA implementation architecture. Classical optimizer interacts with quantum backend through Qiskit primitives: Estimator (Phases 2-3) for measuring $\langle H_C \rangle$ during optimization, and Sampler (Phase 4) for collecting bitstrings with shot budget $N$.