Problems

A problem is a plain, JSON-safe description of a computational task. It isn’t executed and it isn’t an algorithm — an algorithm consumes a problem later. All problems share one contract: validate() -> list[str] (empty = valid) and to_dict() / to_json() serialization.

The five built-in problem types:

Problem	Purpose
SamplingProblem	Sample |bitstring> -> probability from a circuit’s output distribution.
OptimizationProblem	Minimize a binary-objective function (QUBO or spin-Ising view).
HamiltonianProblem	The spectrum of a Hermitian operator.
EigenvalueProblem	The lowest k eigenvalues (subclass of HamiltonianProblem).
SearchProblem	Find marked items in a 2**n-item database.

Creating problems

from microquantum import (
    EigenvalueProblem,
    HamiltonianProblem,
    Operator,
    OptimizationProblem,
    PauliSum,
    QuantumCircuit,
    SamplingProblem,
    SearchProblem,
)
from microquantum.optimization import QUBOBuilder

sampling = SamplingProblem(QuantumCircuit(2), name="bell")
spectrum = HamiltonianProblem(Operator.Z(), name="z")
lowest   = EigenvalueProblem(Operator.Z(), k=2, name="z-k2")

builder = QUBOBuilder(2)
builder.add_linear(0, -1.0)
builder.add_quadratic(0, 1, 2.0)
opt  = OptimizationProblem.from_qubo(builder.build("cut"), name="maxcut")
spin = OptimizationProblem.from_ising(PauliSum.from_label("ZZ", 1.0))

search = SearchProblem(num_qubits=2, target=[1, 2], name="search")

Validation and serialization

problems = opt.validate()      # [] when valid
data = search.to_dict()        # JSON-safe
restored = SearchProblem.from_dict(data)

Positional-first

Payload comes first, mirroring the primary use: HamiltonianProblem(H), EigenvalueProblem(H, k=2) and SamplingProblem(circuit).