QAOAProblem

class QAOAProblem

Bases: ABC

Base class for all QAOA-compatible problems.

Subclasses must implement the abstract properties that provide the ingredients QAOA needs. Default implementations of mixer_hamiltonian, recommended_initial_state, is_feasible, repair_infeasible_bitstring, and compute_energy are provided and can be overridden.

Attributes Summary

cost_hamiltonian	The cost Hamiltonian encoding the optimization objective.
decode_fn	Map a measurement bitstring to a domain-level solution.
loss_constant	Constant offset added back to the expectation value.
mixer_hamiltonian	Mixer Hamiltonian for exploring the solution space.
recommended_initial_state	Recommended initial quantum state for this problem.
wire_labels	Qubit-position-ordered labels for the cost Hamiltonian.

Methods Summary

compute_energy(bitstring)	Evaluate the objective energy for a bitstring.
decompose()	Decompose this problem into sub-problems for partitioned solving.
evaluate_global_solution(solution)	Score a complete global solution for beam search.
extend_solution(current_solution, prog_id, ...)	Map a sub-solution's decoded bits into the global solution vector.
initial_solution_size()	Size of the global solution vector (e.g. number of graph nodes).
is_feasible(bitstring)	Check whether a bitstring represents a feasible solution.
postprocess_candidates(candidates, *[, strict])	Post-process raw partition-aggregation candidates.
repair_infeasible_bitstring(bitstring)	Repair an infeasible bitstring into a feasible one.

Attributes Documentation

cost_hamiltonian

The cost Hamiltonian encoding the optimization objective.

decode_fn

Map a measurement bitstring to a domain-level solution.

Bitstrings use left-to-right qubit ordering: the character at index i corresponds to qubit i of the cost Hamiltonian.

loss_constant

Constant offset added back to the expectation value.

mixer_hamiltonian

Mixer Hamiltonian for exploring the solution space.

Defaults to the standard X mixer over the cost Hamiltonian qubits, suitable for unconstrained binary optimization. Override this for constrained feasible subspaces or problem-specific mixers.

recommended_initial_state

Recommended initial quantum state for this problem.

Defaults to SuperpositionState (ground state of the standard X mixer).

wire_labels

Qubit-position-ordered labels for the cost Hamiltonian.

Defaults to dense range(num_qubits). Override for problems whose users expect domain-level identifiers (e.g. graph node names) at QAOA._circuit_wires and through decode_fn.

Methods Documentation

compute_energy(bitstring)

Evaluate the objective energy for a bitstring.

Defaults to None (unknown).

Return type:

float | None

decompose()

Decompose this problem into sub-problems for partitioned solving.

Returns a dict mapping program IDs to sub-problems. Program IDs must be hashable and stable because later partitioning hooks receive the same IDs when extending candidates into a global solution.

Raises:

NotImplementedError – If the subclass does not support decomposition.

Return type:

dict[Hashable, QAOAProblem]

evaluate_global_solution(solution)

Score a complete global solution for beam search.

Lower scores are better. Problems with maximization objectives should usually return a negated score here, then expose the natural objective value from postprocess_candidates().

Return type:

float

extend_solution(current_solution, prog_id, candidate_decoded)

Map a sub-solution’s decoded bits into the global solution vector.

prog_id is one of the keys returned by decompose(). Must return a new list — do not mutate current_solution.

Return type:

list[int]

initial_solution_size()

Size of the global solution vector (e.g. number of graph nodes).

Return type:

int

is_feasible(bitstring)

Check whether a bitstring represents a feasible solution.

Defaults to True (unconstrained).

Return type:

bool

postprocess_candidates(candidates, *, strict=False)

Post-process raw partition-aggregation candidates.

Parameters:

• candidates (list[tuple[float, list[int]]]) – Beam-search (score, solution) pairs, where score is the value returned by evaluate_global_solution() and lower is better.

• strict (bool) – If supported by a constrained problem, reject invalid raw solutions instead of repairing them. The default implementation ignores this flag.

Return type:

list[tuple[Any, float]]

Returns:

Problem-specific (result, objective_value) tuples ready to return from partitioned aggregation APIs. The objective value uses the problem’s public convention, which may differ from the beam-search score. Default: (solution, score).

repair_infeasible_bitstring(bitstring)

Repair an infeasible bitstring into a feasible one.

Returns:

• repaired_bitstring: The feasible bitstring after repair.

• decoded: Domain-level solution (e.g. tour list, routes), or None if unavailable.

• energy: Objective value of the repaired solution, or None if unknown.

Return type:

tuple[str, Any, float | None]

The default implementation returns the bitstring unchanged.