python v0.6

Qiskit-optimization

Quantum optimization algorithms and QUBO problem formulation for Qiskit

Quick install

pip install qiskit-optimization

Background and History

Qiskit Optimization was created as part of the breakup of Qiskit Aqua into focused domain libraries, which took place between 2021 and 2022. In the original Qiskit architecture, combinatorial optimization algorithms (QAOA, VQE-based optimization, Grover-based search) were bundled alongside chemistry, finance, and machine learning code within the monolithic Aqua package. As Aqua was deprecated, the optimization functionality was extracted and refined into Qiskit Optimization, a standalone library with a cleaner API centered around the QuadraticProgram abstraction.

The library was developed by IBM Quantum’s applications research team, with Stefan Woerner, Julien Gacon, and other contributors shaping its design. The core insight behind Qiskit Optimization’s architecture is that many real-world optimization problems can be expressed as quadratic programs, which can then be converted to QUBO (Quadratic Unconstrained Binary Optimization) formulations suitable for quantum algorithms. The library automates the conversion from constrained optimization problems to QUBOs, handling penalty terms, variable substitutions, and constraint relaxation.

On the solver side, Qiskit Optimization provides wrapper classes that adapt Qiskit’s minimum eigenvalue solvers (including QAOA and VQE) into optimization problem solvers. The MinimumEigenOptimizer maps a QuadraticProgram to a Hamiltonian, solves for the minimum eigenvalue using a quantum or classical algorithm, and maps the result back to the original variable space. The library also includes warm-start techniques and recursive QAOA variants that can improve solution quality on near-term hardware. Portfolio optimization is a prominent use case, with dedicated helper classes for mean-variance formulations.

As of 2025, Qiskit Optimization is maintained by the Qiskit community under the qiskit-community GitHub organization. Like Qiskit Nature, its development pace depends on community contributions, and its long-term maintenance trajectory is less certain than the core Qiskit SDK. The library remains functional and is used in educational contexts and research on quantum optimization algorithms. It competes with D-Wave’s Ocean SDK for optimization use cases, though the two tools target different hardware paradigms (gate-model versus quantum annealing).

Qiskit Optimization provides a high-level QuadraticProgram class for expressing optimization problems using linear and quadratic objectives, linear constraints, and variable bounds. Once a problem is defined, converters transform it into a Quadratic Unconstrained Binary Optimization (QUBO) formulation that can be mapped directly to a quantum Hamiltonian. This pipeline handles the bookkeeping of penalty terms and variable substitutions automatically, so you can work at the problem level rather than the Hamiltonian level.

On the solver side, MinimumEigenOptimizer wraps any Qiskit minimum-eigenvalue solver (QAOA, VQE, NumPyMinimumEigensolver) into a drop-in optimizer for QuadraticProgram instances. QAOAOptimizer applies the Quantum Approximate Optimization Algorithm directly and is well suited for graph problems like Max-Cut and traveling salesman variants. GroverOptimizer provides a quadratic speedup for searching optimal solutions via amplitude amplification. Portfolio optimization is a first-class use case, with helper classes for mean-variance formulations of asset allocation problems.

The library includes classical warm-start strategies and recursive QAOA extensions that can improve solution quality on near-term hardware. Because it converts problems into standard Qiskit circuits, all Aer simulators and IBM Quantum backends are available as execution targets without additional glue code.

Key Imports

# Problem formulation
from qiskit_optimization import QuadraticProgram

# Converters
from qiskit_optimization.converters import (
    QuadraticProgramToQubo,
    InequalityToEquality,
    IntegerToBinary,
    LinearEqualityToPenalty,
)

# Optimizers (quantum and classical wrappers)
from qiskit_optimization.algorithms import (
    MinimumEigenOptimizer,
    GroverOptimizer,
    RecursiveMinimumEigenOptimizer,
    WarmStartQAOAOptimizer,
)

# Application helpers
from qiskit_optimization.applications import Maxcut, Tsp
from qiskit_optimization.applications.optimization_application import OptimizationApplication

# Qiskit algorithm primitives used alongside Optimization
from qiskit_algorithms import QAOA, VQE, NumPyMinimumEigensolver
from qiskit_algorithms.optimizers import COBYLA, SPSA
from qiskit.primitives import Sampler

Core Classes

  • QuadraticProgram - The central problem definition class. Supports binary, integer, and continuous variables, linear and quadratic objective functions, and linear constraints (equalities and inequalities). All other components in the library consume or produce QuadraticProgram instances.
  • QuadraticProgramToQubo - Converter that chains together constraint-to-penalty, integer-to-binary, and inequality-to-equality transformations to produce an unconstrained binary problem suitable for quantum solvers.
  • InequalityToEquality / IntegerToBinary / LinearEqualityToPenalty - Individual converter steps if you need fine-grained control over the QUBO conversion pipeline.
  • MinimumEigenOptimizer - Wraps any Qiskit minimum-eigenvalue solver (QAOA, VQE, NumPyMinimumEigensolver) into an optimizer that accepts a QuadraticProgram, converts it to a Hamiltonian, solves for the minimum eigenvalue, and maps the result back to the original variable space.
  • GroverOptimizer - Uses Grover Adaptive Search to find optimal solutions with a provable quadratic speedup over brute-force search. Requires an oracle construction step and works best on small problem instances.
  • RecursiveMinimumEigenOptimizer - Iteratively fixes variables based on intermediate solutions, reducing the problem size at each step. Can improve solution quality for QAOA on larger instances.
  • WarmStartQAOAOptimizer - Initializes QAOA parameters using the relaxed (continuous) solution, which can speed up convergence and improve solution quality.
  • Maxcut / Tsp - Application helper classes that convert standard combinatorial problems into QuadraticProgram instances with the correct objective and constraints pre-built.

Common Patterns

Max-Cut problem

Define a graph, convert it to a QUBO, and solve with QAOA.

import numpy as np
from qiskit_optimization.applications import Maxcut
from qiskit_optimization.algorithms import MinimumEigenOptimizer
from qiskit_algorithms import QAOA
from qiskit_algorithms.optimizers import COBYLA
from qiskit.primitives import Sampler

# Define a 4-node graph as an adjacency matrix
adjacency_matrix = np.array([
    [0, 1, 1, 0],
    [1, 0, 1, 1],
    [1, 1, 0, 1],
    [0, 1, 1, 0],
])

# Use the Maxcut application helper to build the QuadraticProgram
maxcut = Maxcut(adjacency_matrix)
qp = maxcut.to_quadratic_program()
print(qp.prettyprint())

# Set up QAOA with depth p=1
qaoa = QAOA(sampler=Sampler(), optimizer=COBYLA(maxiter=200), reps=1)

# Wrap QAOA in MinimumEigenOptimizer to solve the QuadraticProgram
optimizer = MinimumEigenOptimizer(qaoa)
result = optimizer.solve(qp)

print(f"Optimal partition: {result.x}")
print(f"Cut value: {result.fval}")

# Interpret the result back to graph partition
partition = maxcut.interpret(result)
print(f"Partition groups: {partition}")

Traveling Salesman (TSP)

Formulate TSP using the application helper, which encodes city ordering as binary decision variables with one-hot constraints.

import numpy as np
from qiskit_optimization.applications import Tsp
from qiskit_optimization.algorithms import MinimumEigenOptimizer
from qiskit_algorithms import NumPyMinimumEigensolver

# Define a 3-city distance matrix
distance_matrix = np.array([
    [0, 10, 15],
    [10, 0, 20],
    [15, 20, 0],
])

# Build the TSP QuadraticProgram with penalty for constraint violations
tsp = Tsp(distance_matrix)
qp = tsp.to_quadratic_program()
print(qp.prettyprint())

# For small instances, use the exact classical solver to verify formulation
exact_solver = MinimumEigenOptimizer(NumPyMinimumEigensolver())
result = exact_solver.solve(qp)

print(f"Solution vector: {result.x}")
print(f"Objective value: {result.fval}")

# Interpret as a city ordering
route = tsp.interpret(result)
print(f"Optimal route: {route}")

For larger instances, replace NumPyMinimumEigensolver with QAOA or VQE. Note that TSP on n cities requires n^2 binary variables, so qubit counts grow quickly.

Portfolio optimization

Use the portfolio optimization helpers for mean-variance asset allocation.

import numpy as np
from qiskit_optimization import QuadraticProgram
from qiskit_optimization.algorithms import MinimumEigenOptimizer
from qiskit_algorithms import QAOA
from qiskit_algorithms.optimizers import COBYLA
from qiskit.primitives import Sampler

# Problem parameters
num_assets = 3
expected_returns = np.array([0.05, 0.10, 0.08])
covariance_matrix = np.array([
    [0.01, 0.002, 0.001],
    [0.002, 0.04, 0.005],
    [0.001, 0.005, 0.02],
])
risk_factor = 0.5  # Trade-off between risk and return
budget = 2          # Select exactly 2 out of 3 assets

# Build the QuadraticProgram manually for mean-variance optimization
qp = QuadraticProgram("portfolio")

# Binary variables: 1 if asset is selected, 0 otherwise
for i in range(num_assets):
    qp.binary_var(name=f"x_{i}")

# Objective: minimize risk_factor * x^T * Sigma * x - mu^T * x
quadratic = risk_factor * covariance_matrix
linear = -expected_returns
qp.minimize(linear=linear, quadratic=quadratic)

# Budget constraint: select exactly `budget` assets
qp.linear_constraint(
    linear={f"x_{i}": 1 for i in range(num_assets)},
    sense="==",
    rhs=budget,
    name="budget",
)

print(qp.prettyprint())

# Solve with QAOA
qaoa = QAOA(sampler=Sampler(), optimizer=COBYLA(maxiter=300), reps=1)
optimizer = MinimumEigenOptimizer(qaoa)
result = optimizer.solve(qp)

print(f"Selected assets: {result.x}")
print(f"Objective value: {result.fval:.6f}")

Classical warm start

Use WarmStartQAOAOptimizer to initialize QAOA from the relaxed continuous solution, which improves convergence on harder instances.

import numpy as np
from qiskit_optimization.applications import Maxcut
from qiskit_optimization.algorithms import WarmStartQAOAOptimizer
from qiskit_algorithms.optimizers import COBYLA
from qiskit.primitives import Sampler

# Define a graph
adjacency_matrix = np.array([
    [0, 1, 1, 1],
    [1, 0, 1, 0],
    [1, 1, 0, 1],
    [1, 0, 1, 0],
])

maxcut = Maxcut(adjacency_matrix)
qp = maxcut.to_quadratic_program()

# WarmStartQAOAOptimizer solves the continuous relaxation first,
# then uses that solution to initialize the QAOA angles
warm_start_optimizer = WarmStartQAOAOptimizer(
    pre_solver=None,  # uses default continuous relaxation
    relax_for_pre_solver=True,
    qaoa=None,  # constructs QAOA internally
    sampler=Sampler(),
    optimizer=COBYLA(maxiter=300),
    reps=1,
    epsilon=0.25,  # rounding threshold for warm-start encoding
)

result = warm_start_optimizer.solve(qp)

print(f"Warm-start solution: {result.x}")
print(f"Cut value: {result.fval}")

Comparison with Similar Tools

D-Wave Ocean SDK targets quantum annealing hardware rather than gate-model quantum computers. Ocean provides BQM and CQM abstractions for formulating optimization problems and can submit them directly to D-Wave annealers. For pure combinatorial optimization on current hardware, D-Wave’s annealers can handle larger problem sizes (thousands of variables) than gate-model QAOA (which is limited to tens of variables on current devices). Choose Ocean if you have access to D-Wave hardware and your problem maps naturally to a QUBO or Ising model.

Google OR-Tools and Gurobi are classical optimization solvers that will outperform any quantum approach on all practically sized problems today. OR-Tools is open-source and excellent for constraint programming, routing, and linear programming. Gurobi is a commercial solver with state-of-the-art performance on mixed-integer programs. Use Qiskit Optimization when you are studying quantum optimization algorithms, benchmarking quantum versus classical approaches, or preparing for a future where quantum hardware can handle larger instances. For production optimization workloads in 2025, classical solvers remain the correct choice.

Learning Resources