IterativeQAOA¶

class IterativeQAOA(problem, *, max_depth=5, strategy=InterpolationStrategy.INTERP, n_basis_terms=None, max_iterations_per_depth=10, convergence_threshold=None, **kwargs)[source]¶

Bases: QAOA

Iterative QAOA with parameter interpolation across increasing depths.

Instead of optimizing at a single fixed depth, this class iteratively increases the circuit depth from 1 to max_depth, using the optimal parameters from depth p as a warm-start for depth p+1 via an interpolation strategy.

After run() completes, the instance represents the depth that achieved the best loss. All standard QAOA properties (solution, best_params, best_loss, get_top_solutions) work as usual.

Example:

iterative = IterativeQAOA(
    problem=MaxCutProblem(graph),
    max_depth=5,
    strategy=InterpolationStrategy.INTERP,
    max_iterations_per_depth=20,
    backend=backend,
    optimizer=ScipyOptimizer(ScipyMethod.COBYLA),
)
iterative.run()
print(iterative.best_depth)
print(iterative.solution)

Parameters:

problem – A QAOAProblem instance providing the QAOA ingredients.
max_depth (int) – Maximum circuit depth to iterate up to. Defaults to 5.
strategy (InterpolationStrategy) – Interpolation strategy for warm-starting. Defaults to INTERP.
n_basis_terms (int | None) – Number of basis terms for FOURIER/CHEBYSHEV strategies. Ignored for INTERP. Defaults to min(p, 5) when None.
max_iterations_per_depth (int | Callable[[int], int]) – Maximum optimization iterations per depth. Can be an integer (same for all depths) or a callable (depth) -> int for adaptive budgets. Defaults to 10.
convergence_threshold (float | None) – If set, stop iterating when the absolute improvement in loss between consecutive depths is below this value.
**kwargs – All remaining QAOA keyword arguments (backend, optimizer, initial_state, etc.).

Initialize the QAOA algorithm.

Parameters:

problem – A QAOAProblem instance that provides cost/mixer Hamiltonians, loss constant, decode function, and recommended initial state.
initial_state – Override the problem’s recommended initial state. If None, uses problem.recommended_initial_state.
trotterization_strategy – Strategy for Hamiltonian evolution. Defaults to ExactTrotterization.
max_iterations – Maximum number of optimization iterations. Defaults to 10.
n_layers – Number of QAOA layers (circuit depth). Defaults to 1.
**kwargs – Passed to VariationalQuantumAlgorithm, including optimizer, backend, shots, etc.

Attributes Summary

`best_depth`	The circuit depth that achieved the best (lowest) loss.
`depth_history`	Per-depth optimization results.

Methods Summary

run([initial_params, ...])

Run the iterative QAOA procedure across increasing depths.

Attributes Documentation

best_depth¶: The circuit depth that achieved the best (lowest) loss.

depth_history¶

Per-depth optimization results.

Each entry is a dict with keys: depth, best_loss, best_params, n_iterations.

Methods Documentation

run(initial_params=None, perform_final_computation=True, checkpoint_config=None, **kwargs)[source]¶

Run the iterative QAOA procedure across increasing depths.

At each depth from 1 to max_depth, the algorithm optimizes the QAOA parameters, then interpolates the best parameters to warm-start the next depth. After all depths are explored, the instance is restored to the depth that achieved the best overall loss.

Parameters:

initial_params – Ignored — each depth computes its own warm-start via interpolation of the previous depth’s best parameters. Passing a non-None value emits a UserWarning.
perform_final_computation – Whether to run the final measurement at the best depth to extract the solution. Defaults to True.
checkpoint_config – Forwarded to each inner super().run().
**kwargs – Additional keyword arguments passed to the parent run().

Returns:

Returns self for method chaining.

Return type:

IterativeQAOA