QAOA

A flexible, modular Python library for the Quantum Approximate Optimization Algorithm / Quantum Alternating Operator Ansatz (QAOA), designed for research and experimentation. Swap problems, mixers, initial states, optimizers, and backends without rewriting your code.

---

Table of Contents

• Installation
• Requirements
• Quick Example
• Background
• Custom Ansatz
• Running Optimization
• Further Parameters
• Extracting Results
• Multi-Angle QAOA
• Fixing One Node to Reduce Circuit depth/width
• Building Circuits like Lego
• Minimizing Circuit Depth
• Repository Structure
• Agent
• Citation
• Acknowledgement

---

Installation

pip install qaoa

Or install in development mode from source:

git clone https://github.com/OpenQuantumComputing/QAOA.git
cd QAOA
pip install -e .

---

Requirements

• Python ≥ 3.9
• qiskit ≥ 2.3.0
• qiskit-aer ≥ 0.17.0
• qiskit-algorithms ≥ 0.4.0
• numpy, scipy, matplotlib, networkx

Optional (for the agent):

• langchain, langchain_community, langchain_chroma, langchain_openai, streamlit

---

Quick Example

import networkx as nx
from qaoa import QAOA, problems, mixers, initialstates

# Build a random graph
G = nx.random_regular_graph(3, 8, seed=42)

# Define QAOA components
qaoa = QAOA(
    problem=problems.MaxCut(G),
    mixer=mixers.X(),
    initialstate=initialstates.Plus()
)

# Sample cost landscape at depth p=1
qaoa.sample_cost_landscape()

# Optimize to depth p=3
qaoa.optimize(depth=3)

# Extract results
print("Optimal expectation value:", qaoa.get_Exp(depth=3))
print("Optimal parameters (gamma):", qaoa.get_gamma(depth=3))
print("Optimal parameters (beta):", qaoa.get_beta(depth=3))

See examples/ for more complete worked examples.

---

Background

Given a cost function $$c: \lbrace 0, 1\rbrace^n \rightarrow \mathbb{R}$$ one defines a problem Hamiltonian $H_P$ through the action on computational basis states via

$$ H_P |x\rangle = c(x) |x\rangle,$$

which means that ground states minimize the cost function $c$. Given a parametrized ansatz $| \gamma, \beta \rangle$, a classical optimizer is used to minimize the energy

$$ \langle \gamma, \beta | H_P | \gamma, \beta \rangle.$$

QAOA of depth $p$ consists of the following ansatz:

$$ |\gamma, \beta \rangle = \prod_{l=1}^p \left( U_M(\beta_l) U_P(\gamma_l)\right) | s\rangle, $$

where

• $U_P$ is a family of phase-separating operators,
• $U_M$ is a family of mixing operators, and
• $|s\rangle$ is a "simple" initial state.

In plain vanilla QAOA these have the form $U_M(\beta_l)=e^{-i\beta_l X^{\otimes n}}$, $U_P(\gamma_l)=e^{-i\gamma_l H_P}$, and the uniform superposition $| s \rangle = |+\rangle^{\otimes n}$ as initial state.

---

Custom Ansatz

To create a custom QAOA ansatz, specify a problem, a mixer, and an initial state. These base classes each have an abstract method def create_circuit: that must be implemented. The problem base class additionally requires def cost:.

This library already contains several standard implementations.

• The following problem cases are already available:
  • Max k-CUT binary power of two
  • Max k-CUT binary full H
  • Max k-CUT binary one hot
  • QUBO
  • Exact cover
  • Portfolio
  • Graph
• The following mixer cases are already available:
  • X-mixer
  • XY-mixer
  • Grover-mixer
  • Max k-CUT grover
  • Max k-CUT LX
  • X multi-angle mixer (one β per qubit)
• The following initial state cases are already available:
  • Plus
  • Statevector
  • Dicke
  • Dicke 1- and 2-states superposition
  • Less than k
  • Max k-CUT feasible
  • Plus parameterized (|+⟩ with optimizable phase rotations)

It is very easy to extend this list by implementing the abstract methods of the base classes above. Feel free to fork the repo and open a pull request!

See examples/MaxCut/OverlapInitialState.ipynb for a study of how the overlap between the initial state and the X-mixer ground state affects QAOA performance at various circuit depths.

See examples/MaxCut/KCutExamples.ipynb for worked examples of Max k-cut using both one-hot and binary encodings.

For example, to set up QAOA for MaxCut using the X-mixer and $|+\rangle^{\otimes n}$ as the initial state:

qaoa = QAOA(
    problem=problems.MaxCut(G),
    mixer=mixers.X(),
    initialstate=initialstates.Plus()
)

---

Running Optimization at Depth $p$

For depth $p=1$ the expectation value can be sampled on an $n\times m$ Cartesian grid over the domain $[0,\gamma_\text{max}]\times[0,\beta_\text{max}]$ with:

qaoa.sample_cost_landscape()

Sampling high-dimensional target functions quickly becomes intractable for depth $p>1$. The library therefore iteratively increases the depth. At each depth a local optimization algorithm (e.g. COBYLA) finds a local minimum, using the following initial guess:

• At depth $p=1$: parameters $(\gamma, \beta)$ are taken from the minimum of the sampled cost landscape.

• At depth $p>1$: two strategies are available, controlled by the interpolate parameter:

  • Interpolation (interpolate=True, default): uses the INTERP heuristic to produce a smooth initial guess by interpolating the optimal angles from depth $p-1$. Works well for vanilla QAOA.

  • Layer-by-layer grid scan (interpolate=False): the best angles from depth $p-1$ are locked and a 2-D grid search is performed over the new layer's parameters. Because the grid includes $(γ=0, β=0)$ — which adds an identity layer reproducing the depth-$(p-1)$ result — the initial cost at depth $p$ is guaranteed to be ≤ cost at depth $p-1$, ensuring a monotonically increasing approximation ratio. Recommended for multi-angle and orbit ansätze.

# Interpolation (default)
qaoa = QAOA(..., interpolate=True)
qaoa.optimize(depth=p)

# Layer-by-layer grid scan
qaoa = QAOA(..., interpolate=False)
qaoa.optimize(depth=p)

This will call sample_cost_landscape automatically if it has not been run yet.

---

Further Parameters

qaoa = QAOA(
    ...,
    backend=,
    noisemodel=,
    optimizer=,
    precision=,
    shots=,
    cvar=
)

• backend: the backend to use, defaults to AerSimulator() from qiskit_aer
• noisemodel: noise model to apply, defaults to None
• optimizer: optimizer from qiskit-algorithms with options, defaults to [COBYLA, {}]
• precision: sample until a certain precision of the expectation value is reached, based on $\text{error}=\frac{\text{variance}}{\sqrt{\text{shots}}}$, defaults to None
• shots: number of measurement shots, defaults to 1024
• cvar: value for Conditional Value at Risk (CVaR), defaults to 1 (standard expectation value)

---

Extract Results

Once qaoa.optimize(depth=p) is run, extract the expectation value, variance, and parameters for each depth $1\leq i \leq p$:

qaoa.get_Exp(depth=i)
qaoa.get_Var(depth=i)
qaoa.get_gamma(depth=i)
qaoa.get_beta(depth=i)

Additionally, for every optimizer call at each depth, the angles, expectation value, variance, maximum cost, minimum cost, and number of shots are stored in:

qaoa.optimization_results[i]

---

Multi-Angle QAOA

Multi-angle QAOA allows components to use multiple parameters per layer, increasing expressibility:

• Multi-angle mixer (XMultiAngle): each qubit gets its own independent β parameter.
• Parameterized initial state (PlusParameterized): the initial state |+⟩ with optimizable per-qubit phase rotations.

qaoa = QAOA(
    problem=problems.MaxCut(G),
    mixer=mixers.XMultiAngle(),   # N_qubits beta parameters per layer
    initialstate=initialstates.Plus()
)

The flat angle array format used by hist(), getParametersToBind(), and interp() is:

[init_0, ..., init_{n-1},          # initial state params (0 for Plus)
 gamma_{0,0}, ..., beta_{0,n-1},   # layer 0 params
 gamm