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

TL;DR

Migrating QAOA from Qiskit 1.x to 2.x revealed that default sampling settings significantly impact algorithm accuracy, emphasizing the need for careful parameter management to ensure reproducibility.

Contribution

This paper systematically analyzes the impact of sampling parameters during QAOA migration between Qiskit versions, providing insights and recommendations for reliable quantum software development.

Findings

Default shots in Qiskit 2.x limit state space exploration

Increasing shots improves accuracy and reproducibility

Hidden parameters can dominate hybrid quantum-classical algorithms

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.