microquantum.problems.search

Generic search problem abstraction.

A SearchProblem describes an unstructured database search: find one (or more) of the 2^num_qubits computational basis states that satisfy a predicate. The predicate can be supplied three different ways (at most one):

• target — an integer index (or list of indices) of the sought state(s);

• oracle — a callable oracle(num_qubits) -> QuantumCircuit marking the solution subspace;

• predicate — a callable predicate(index) -> bool over the integer index of a computational basis state; used to classically expand the marked set.

The problem stays decoupled from the algorithm (e.g. Grover).

Module Contents

class microquantum.problems.search.SearchProblem

Bases: microquantum.problems.base.Problem

Search the 2^num_qubits-element database for marked state(s).

Exactly one of target / oracle / predicate should be given.

Variables:

• num_qubits – Size of the search register.

• target – Integer, list of integers, or MSB-first bitstring (e.g. "101") identifying the solution basis state(s). Bitstrings are normalized to integers on construction.

• oracle – Callable returning a circuit that marks the solutions.

• predicate – Callable predicate(bitstring) -> bool.

• num_targets – Number of marked states (only used for the optimal iteration estimate when num_qubits is set without a target).

num_qubits: int = 1

target: int | list[int] | str | None = None

oracle: Callable[[int], Any] | None = None

predicate: Callable[[int], bool] | None = None

num_targets: int = 1

validate()

Return a list of validation problems (empty means valid).

Return type:

list[str]

target_indices()

Return the integer indices of the marked states (if known).

Return type:

list[int]

is_marked(bitstring)

True if bitstring (of length num_qubits) is a solution.

Parameters:

bitstring (str)

Return type:

bool

num_solutions()

Number of marked states (best-effort estimate).

Return type:

int

to_dict()

Serialize to a JSON-safe dictionary.

Return type:

dict[str, Any]

classmethod from_dict(data)

Reconstruct a SearchProblem from its serialized dictionary.

The target-based form round-trips exactly; oracle/predicate callables are not serialized and default to None.

Parameters:

data (dict[str, Any])

Return type:

SearchProblem