BeamSearchStrategy

class BeamSearchStrategy(beam_width=1, n_partition_candidates=None)

Bases: AggregationStrategy

Left-to-right beam search over partitions.

At each partition step, every retained partial solution is extended by every fetched candidate, all extensions are scored, and only the best beam_width are kept. beam_width=1 is greedy; beam_width=None is exhaustive.

Parameters:

• beam_width (int | None) – Maximum candidates to retain per partition step. None keeps all extensions (exhaustive). Internally bumped to at least top_n so the beam can return enough solutions.

• n_partition_candidates (int | None) – Candidates to fetch from each partition. Defaults to beam_width (or all when exhaustive). Must be >= beam_width.

Attributes Summary

beam_width
n_partition_candidates

Methods Summary

aggregate(programs, initial_solution, ...[, ...])

Aggregate per-partition candidates into the top-N global solutions.

Attributes Documentation

beam_width: int | None = 1

n_partition_candidates: int | None = None

Methods Documentation

aggregate(programs, initial_solution, extend_fn, evaluate_fn, top_n=1)

Aggregate per-partition candidates into the top-N global solutions.

Parameters:

• programs (dict[Any, SolutionSamplingMixin]) – Mapping of program IDs to executed VariationalQuantumAlgorithm instances.

• initial_solution (Sequence[int]) – Starting global solution vector (typically all zeros).

• extend_fn (Callable[[list[int], Any, SolutionEntry], list[int]]) – (current_solution, prog_id, candidate) -> extended_solution; splices a partition’s candidate into the global vector.

• evaluate_fn (Callable[[list[int]], float]) – (solution) -> float. Lower is better.

• top_n (int) – Number of top solutions to return.

Return type:

list[tuple[float, list[int]]]

Returns:

List of (score, solution) tuples sorted ascending by score (best first), with at most top_n entries.