Overview

A problem is a plain, JSON-safe description of a computational task — never an execution and never an algorithm. Problems feed Algorithms, which translate them into circuits and run them.

The problem contract

Every problem subclasses Problem and provides:

• validate() -> list[str] — human-readable diagnostics (empty list = valid). Never raises.

• to_dict() / from_dict() and to_json() / from_json() — JSON-safe serialization.

• type / name metadata.

The five built-ins

Problem	Generalization
SamplingProblem	Obtain samples |bitstring> -> probability from a circuit’s output distribution. Payload: a circuit.
OptimizationProblem	Minimize a binary-objective function, in QUBO or spin-Ising view. Payload: QUBO/Ising coefficients.
HamiltonianProblem	The spectrum of a Hermitian operator. Payload: an Operator or PauliSum.
EigenvalueProblem	Like HamiltonianProblem, but requests the lowest k eigenvalues.
SearchProblem	Find marked items in a 2**num_qubits-item database. Payload: a target list or predicate.

Design notes

• Positional-first payloads: SamplingProblem(circuit), HamiltonianProblem(H), EigenvalueProblem(H, k=2) — the payload is the first argument.

• Hamiltonian-backed problems serialize through hamiltonian_to_dict (labeled Pauli terms with complex coefficients or an explicit matrix).

• Problems are the input contract of the SDK; results are never a problem.