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

2025-12-08

AI Summary

During the Qiskit 1.x→2.x migration, the default shot count for QAOA was drastically reduced, causing insufficient state-space coverage (only 23%) and leading to output distribution shifts and significant accuracy degradation—undermining reproducibility. Method: We developed a standardized QAOA implementation based on Qiskit 2.x v2 primitives, rigorously controlling circuit construction, optimizer selection, and Hamiltonian encoding, and systematically quantified performance decay across varying shot counts. Contribution/Results: We identified the shot reduction as the root cause and proposed a reproducibility-preserving shot count of 250,000, which fully restores original accuracy. This work is the first to expose the critical impact of implicit parameters in the quantum-classical interface layer on hybrid algorithm performance. It establishes a parameter calibration paradigm and empirical benchmark for quantum software version migration, enabling robust cross-version algorithm deployment.

Technology Category

• Machine Learning: Quantum Machine Learning
• Search and Optimization: Mixed Discrete/Continuous Search
• Constraint Satisfaction and Optimization: Other Foundations of Constraint Satisfaction

Application Category

• Search and Retrieval-Augmented AI: Web learning to rank, online learning, and counterfactual learning for ranking
• Responsible Web: Human-perceived consequences of algorithmic deployment on the web
• Security and Privacy: Data transparency and provenance

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.

Problem

• Migrating QAOA from Qiskit 1.x to 2.x reveals hidden behavioral changes affecting accuracy
• The root cause is the sampling budget (shots per iteration) impacting probability distributions
• Hidden parameters at quantum-classical interaction level dominate hybrid algorithm performance reproducibility

Innovation

• Migrated QAOA from Qiskit 1.x to 2.x
• Identified sampling budget as key performance factor
• Increased shots to 250,000 for accuracy restoration