PartitioningProgramEnsemble

class PartitioningProgramEnsemble(problem, n_layers, backend, optimizer, quantum_routine='qaoa', max_iterations=10, **kwargs)

Bases: ProgramEnsemble

Generic orchestrator for partition-solve-aggregate quantum optimization.

Delegates all domain-specific logic to the QAOAProblem instance: decomposition, solution extension, evaluation, and result post-processing. The ensemble handles program creation, execution, and beam search.

Parameters:

• problem (QAOAProblem) – A QAOAProblem configured for decomposition (e.g. MaxCutProblem(graph, partitioning_config=...)).

• n_layers (int) – Number of ansatz layers per sub-program.

• backend (CircuitRunner) – Backend for circuit execution.

• optimizer (Optimizer) – Optimizer for each sub-program.

• quantum_routine (Literal['qaoa', 'pce', 'iterative_qaoa']) – Per-partition quantum algorithm. "qaoa" (default), "pce", or "iterative_qaoa".

• max_iterations (int) – Max optimization iterations per sub-program.

• **kwargs – If early_stopping is present it is extracted and deep-copied per sub-program. Remaining kwargs are forwarded to the engine constructor.

Methods Summary

aggregate_results([beam_width, ...])	Aggregate partition results into a global solution via beam search.
create_programs()	Decompose the problem and create quantum programs for each sub-problem.
get_top_solutions([n, beam_width, ...])	Get the top-N global solutions from beam search aggregation.

Methods Documentation

aggregate_results(beam_width=1, n_partition_candidates=None)

Aggregate partition results into a global solution via beam search.

Parameters:

• beam_width – Beam width. 1 is greedy; None is exhaustive.

• n_partition_candidates – Candidates fetched per partition. Defaults to beam_width.

Returns:

Problem-specific post-processed result (see QAOAProblem.postprocess_candidates), or None if post-processing rejects all candidates.

create_programs()

Decompose the problem and create quantum programs for each sub-problem.

get_top_solutions(n=10, *, beam_width=1, n_partition_candidates=None, strict=False)

Get the top-N global solutions from beam search aggregation.

Parameters:

• n – Number of top solutions to return (>= 1).

• beam_width – Beam search width.

• n_partition_candidates – Candidates per partition.

• strict (bool) – Ask problem-specific post-processing to reject invalid raw constrained solutions rather than repair them. The returned list may contain fewer than n entries for constrained problems.

Returns:

Problem-specific post-processed results (see QAOAProblem.postprocess_candidates).