QAOA

class QAOA(problem, *, initial_state=None, trotterization_strategy=None, max_iterations=10, n_layers=1, **kwargs)

Bases: VariationalQuantumAlgorithm

Quantum Approximate Optimization Algorithm (QAOA) implementation.

QAOA is a hybrid quantum-classical algorithm designed to solve combinatorial optimization problems. It alternates between applying a cost Hamiltonian (encoding the problem) and a mixer Hamiltonian (enabling exploration).

The problem is provided as a QAOAProblem instance that supplies the cost Hamiltonian, mixer Hamiltonian, initial state, loss constant, and decode function.

Parameters:

• problem (QAOAProblem) – A QAOAProblem instance providing the QAOA ingredients.

• initial_state (InitialState | None) – Override the problem’s recommended initial state.

• trotterization_strategy (TrotterizationStrategy | None) – The trotterization strategy. Defaults to ExactTrotterization.

• max_iterations (int) – Maximum number of optimization iterations. Defaults to 10.

• n_layers (int) – Number of QAOA layers. Defaults to 1.

• **kwargs – Additional keyword arguments passed to VariationalQuantumAlgorithm, including optimizer and backend.

Initialize the QAOA algorithm.

Parameters:

• problem (QAOAProblem) – A QAOAProblem instance that provides cost/mixer Hamiltonians, loss constant, decode function, and recommended initial state.

• initial_state (InitialState | None) – Override the problem’s recommended initial state. If None, uses problem.recommended_initial_state.

• trotterization_strategy (TrotterizationStrategy | None) – Strategy for Hamiltonian evolution. Defaults to ExactTrotterization.

• max_iterations (int) – Maximum number of optimization iterations. Defaults to 10.

• n_layers (int) – Number of QAOA layers (circuit depth). Defaults to 1.

• **kwargs – Passed to VariationalQuantumAlgorithm, including optimizer, backend, shots, etc.

Attributes Summary

n_params_per_layer	Number of trainable parameters per ansatz layer.
solution	Get the solution found by QAOA optimization.
solution_bitstring	Most-probable bitstring measured at the optimized parameters.

Methods Summary

get_top_solutions([n, min_prob, ...])	Get top-N solutions with optional feasibility filtering and repair.
sample_solution([params])	Run measurement circuits with the given parameters and decode the solution.

Attributes Documentation

n_params_per_layer

solution

Get the solution found by QAOA optimization.

The return type depends on the Problem’s decode function; None is a legitimate decoded value after .run().

Raises:

RuntimeError – If .run() has not yet been called.

solution_bitstring

Most-probable bitstring measured at the optimized parameters.

Always a string of 0/1 characters of length n_qubits, regardless of how the problem’s decode function shapes solution.

Raises:

RuntimeError – If .run() has not yet been called.

Methods Documentation

get_top_solutions(n=10, *, min_prob=0.0, include_decoded=False, feasibility='ignore')

Get top-N solutions with optional feasibility filtering and repair.

Parameters:

• n (int) – Number of top solutions to return (0 = all). Defaults to 10.

• min_prob (float) – Minimum probability threshold. Defaults to 0.0.

• include_decoded (bool) – Include decoded representations. Defaults to False.

• feasibility (Literal['ignore', 'filter', 'repair']) –

  How to handle infeasible solutions:

  • "ignore" (default): return all solutions, ranked by probability.

  • "filter": drop infeasible solutions, rank by objective energy. This implements the PHQC (Polynomial-time Hybrid Quantum-Classical) post-processing from arXiv:2511.14296 (Algorithm 4): every sampled bitstring is checked for feasibility and scored by compute_energy (the true objective, not the penalty Hamiltonian), then the lowest-energy feasible solution is returned.

  • "repair": repair infeasible solutions via the Problem’s repair_infeasible_bitstring method, rank by energy.

Return type:

list[SolutionEntry]

Returns:

List of SolutionEntry.

sample_solution(params=None, **kwargs)

Run measurement circuits with the given parameters and decode the solution.

Return type:

QAOA