microquantum.problems.optimization

Generic combinatorial optimization problem abstraction.

An OptimizationProblem describes an objective over binary variables without encoding how it is optimized. It supports two equivalent, interchangeable views of the same problem:

• an objective function objective(bits) -> float over binary vectors,

• an Ising Hamiltonian (spin variables) cost_hamiltonian().

Classmethods OptimizationProblem.from_qubo() and OptimizationProblem.from_ising() construct problems from the QUBO / Ising formulations used by combinatorial-optimization tooling, so the same problem object stays usable by algorithms (QAOA) as well as classical brute-force evaluation.

Module Contents

class microquantum.problems.optimization.OptimizationProblem

Bases: microquantum.problems.base.Problem

Minimize an objective over num_variables binary variables.

Variables:

• num_variables – Number of binary variables.

• objective – Optional objective(bits) -> float over a binary vector. Required unless ising is provided.

• ising – Optional spin-representation Hamiltonian (PauliSum).

• sampler – Optional sampler(num_variables) -> bits used by algorithms to sample candidate solutions classically.

num_variables: int = 1

objective: Callable[[numpy.ndarray], float] | None = None

ising: Any | None = None

sampler: Callable[[int], numpy.ndarray] | None = None

validate()

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

Return type:

list[str]

classmethod from_ising(pauli_sum, *, name='optimization')

Build a problem whose Ising cost Hamiltonian is pauli_sum.

Parameters:

• pauli_sum (Any)

• name (str)

Return type:

OptimizationProblem

classmethod from_qubo(qubo, *, name='optimization')

Build a problem from a QUBOProblem.

The objective is the QUBO energy and the Ising view is derived via the standard QUBO -> Ising mapping.

Parameters:

• qubo (Any)

• name (str)

Return type:

OptimizationProblem

cost_hamiltonian()

Return the Ising cost Hamiltonian (PauliSum).

Raises:

ValueError – If the problem was defined purely by a binary objective and carries no Ising view.

Return type:

Any

to_qubo()

Convert the Ising view back to a QUBOProblem when available.

Return type:

Any

energy(bits)

Evaluate the objective (or the Ising Hamiltonian) on a bit vector.

Parameters:

bits (numpy.ndarray) – Binary vector of shape (num_variables,).

Raises:

ValueError – If the vector has the wrong length.

Return type:

float

encode_spins(bits)

Map a binary vector to spin values s = 1 - 2 * x.

Parameters:

bits (numpy.ndarray)

Return type:

numpy.ndarray

sample(seed=None)

Sample a candidate bit vector classically.

Uses the problem’s sampler when provided; otherwise a uniform random bit vector (seed applied).

Parameters:

seed (Optional[int])

Return type:

numpy.ndarray

property qubits_needed: int

Number of qubits an exact solver must allocate for this problem.

Return type:

int

to_dict()

Serialize to a JSON-safe dictionary.

Return type:

dict[str, Any]

microquantum.problems.optimization.standard_binary_encoding(value, num_bits)

Encode a non-negative integer as a binary bit vector (MSB first).

Parameters:

• value (int) – Integer in [0, 2**num_bits) to encode.

• num_bits (int) – Number of bits (variables) to use.

Returns:

Float bit vector of length num_bits.

Return type:

numpy.ndarray