qamomile.optimization.post_process

Overview¶

Classes¶

LocalSearch [source]¶

class LocalSearch

Local search energy minimizer for :class:BinaryModel.

Greedily flips single bits that strictly lower the model’s energy (calc_energy), so lower is better — the search terminates at a local minimum where no single-bit flip further decreases energy.

Supports arbitrary-order Ising / HUBO models. Internally converts the model to SPIN representation (±1) for the search, then converts the result back to the original vartype.

Accepts either a :class:BinaryModel directly or an :class:ommx.v1.Instance, matching the other optimization converters. An ommx instance is lowered to a BINARY model via :meth:ommx.v1.Instance.to_hubo, preserving higher-order terms so that HUBO objectives survive the handoff. When an ommx instance is used as input, :meth:run returns an :class:ommx.v1.Solution evaluated against that instance; otherwise it returns a :class:BinarySampleSet.

Parameters:

Raises:

• TypeError — If model is neither a BinaryModel nor an ommx.v1.Instance.

Constructor¶

def __init__(self, model: ommx.v1.Instance | BinaryModel) -> None

Attributes¶

• num_bits: int Number of bits the local search flips, including any slack bits.

Methods¶

run¶

def run(
    self,
    initial_state: Sequence[int] | np.ndarray | ommx.v1.Solution,
    max_iter: int = -1,
    method: str | LocalSearchMethod = LocalSearchMethod.BEST,
) -> BinarySampleSet | ommx.v1.Solution

Run local search starting from initial_state.

Minimizes the model’s energy: only strictly energy-decreasing flips are accepted, so the returned state is a local minimum (lower is better), not necessarily the global optimum.

Parameters:

Returns:

BinarySampleSet | ommx.v1.Solution — The energy-minimized state. If this LocalSearch was BinarySampleSet | ommx.v1.Solution — constructed from an :class:ommx.v1.Instance, the return BinarySampleSet | ommx.v1.Solution — value is an :class:ommx.v1.Solution evaluated against that BinarySampleSet | ommx.v1.Solution — instance (carrying objective, feasibility, and constraint BinarySampleSet | ommx.v1.Solution — values). Otherwise it is a :class:BinarySampleSet with a BinarySampleSet | ommx.v1.Solution — single sample in the model’s original vartype.

Raises:

• ValueError — If method is not recognized, initial_state has wrong length or invalid values, max_iter is less than -1, or initial_state is an :class:ommx.v1.Solution that does not cover the instance’s used decision variables (or LocalSearch was constructed from a :class:BinaryModel, so there is no instance for the Solution to be interpreted against).

LocalSearchMethod [source]¶

class LocalSearchMethod(enum.StrEnum)

Strategy for picking which bit to flip at each local-search step.

Both variants only accept strictly improving flips; the difference is in how the next flip is chosen.

Attributes¶

• BEST

• FIRST

qamomile.optimization.post_process.local_search¶

Local search post-processing for binary optimization models.

Provides first-improvement and best-improvement local search algorithms that operate on :class:BinaryModel instances (both SPIN and BINARY).

Overview¶

Classes¶

BinaryModel [source]¶

class BinaryModel(Generic[VT])

Constructor¶

def __init__(self, expr: BinaryExpr[VT]) -> None

Attributes¶

• coefficients: dict[tuple[int, ...], float] All coefficients as a single flat dictionary using sequential indices.

• constant: float

• higher: dict[tuple[int, ...], float]

• index_new_to_origin

• index_origin_to_new

• linear: dict[int, float]

• num_bits: int

• order

• quad: dict[tuple[int, int], float]

• vartype: VT

Methods¶

calc_energy¶

def calc_energy(self, state: list[int]) -> float

Calculate the energy for a given variable assignment.

Parameters:

Returns:

float — The energy value.

Raises:

• ValueError — If state values are invalid for the vartype.

change_vartype¶

def change_vartype(self, vartype: VarType) -> 'BinaryModel'

decode_from_sampleresult¶

def decode_from_sampleresult(self, result: SampleResult[list[int]]) -> BinarySampleSet[VT]

Decode quantum measurement results into samples with energies.

Converts raw measurement bitstrings (0/1 from quantum hardware) into the model’s variable domain and calculates energies.

Parameters:

Returns:

BinarySampleSet[VT] — BinarySampleSet with samples in expression domain, using original indices

from_hubo¶

@classmethod
def from_hubo(
    cls,
    hubo: dict[tuple[int, ...], float],
    constant: float = 0.0,
    simplify: bool = False,
) -> 'BinaryModel'

Create a BINARY BinaryModel from HUBO coefficients.

Parameters:

Returns:

'BinaryModel' — BinaryModel with BINARY vartype.

from_ising¶

@classmethod
def from_ising(
    cls,
    linear: dict[int, float],
    quad: dict[tuple[int, int], float],
    constant: float = 0.0,
    simplify: bool = False,
) -> 'BinaryModel'

from_qubo¶

@classmethod
def from_qubo(
    cls,
    qubo: dict[tuple[int, int], float],
    constant: float = 0.0,
    simplify: bool = False,
) -> 'BinaryModel'

normalize_by_abs_max¶

def normalize_by_abs_max(self, replace: bool = False) -> BinaryModel[VT]

Normalize the BinaryModel by its absolute maximum coefficient.

Returns:

BinaryModel[VT] — BinaryModel[VT]: The normalized binary model.

normalize_by_factor¶

def normalize_by_factor(self, factor: float, replace: bool = False) -> BinaryModel[VT]

Normalize the BinaryModel by a given factor.

Parameters:

Returns:

BinaryModel[VT] — BinaryModel[VT]: The normalized binary model.

normalize_by_rms¶

def normalize_by_rms(self, replace: bool = False) -> BinaryModel[VT]

Normalize the BinaryModel by its root mean square.

Returns:

BinaryModel[VT] — BinaryModel[VT]: The normalized binary model.

BinarySampleSet [source]¶

class BinarySampleSet(Generic[VT])

Constructor¶

def __init__(
    self,
    samples: list[dict[int, int]],
    num_occurrences: list[int],
    energy: list[float],
    vartype: VT = VarType.BINARY,
) -> None

Attributes¶

• energy: list[float]

• num_occurrences: list[int]

• samples: list[dict[int, int]]

• vartype: VT

Methods¶

energy_mean¶

def energy_mean(self) -> float

lowest¶

def lowest(self) -> tuple[dict[int, int], float, int]

LocalSearch [source]¶

class LocalSearch

Local search energy minimizer for :class:BinaryModel.

Greedily flips single bits that strictly lower the model’s energy (calc_energy), so lower is better — the search terminates at a local minimum where no single-bit flip further decreases energy.

Supports arbitrary-order Ising / HUBO models. Internally converts the model to SPIN representation (±1) for the search, then converts the result back to the original vartype.

Accepts either a :class:BinaryModel directly or an :class:ommx.v1.Instance, matching the other optimization converters. An ommx instance is lowered to a BINARY model via :meth:ommx.v1.Instance.to_hubo, preserving higher-order terms so that HUBO objectives survive the handoff. When an ommx instance is used as input, :meth:run returns an :class:ommx.v1.Solution evaluated against that instance; otherwise it returns a :class:BinarySampleSet.

Parameters:

Raises:

• TypeError — If model is neither a BinaryModel nor an ommx.v1.Instance.

Constructor¶

def __init__(self, model: ommx.v1.Instance | BinaryModel) -> None

Attributes¶

• num_bits: int Number of bits the local search flips, including any slack bits.

Methods¶

run¶

def run(
    self,
    initial_state: Sequence[int] | np.ndarray | ommx.v1.Solution,
    max_iter: int = -1,
    method: str | LocalSearchMethod = LocalSearchMethod.BEST,
) -> BinarySampleSet | ommx.v1.Solution

Run local search starting from initial_state.

Minimizes the model’s energy: only strictly energy-decreasing flips are accepted, so the returned state is a local minimum (lower is better), not necessarily the global optimum.

Parameters:

Returns:

BinarySampleSet | ommx.v1.Solution — The energy-minimized state. If this LocalSearch was BinarySampleSet | ommx.v1.Solution — constructed from an :class:ommx.v1.Instance, the return BinarySampleSet | ommx.v1.Solution — value is an :class:ommx.v1.Solution evaluated against that BinarySampleSet | ommx.v1.Solution — instance (carrying objective, feasibility, and constraint BinarySampleSet | ommx.v1.Solution — values). Otherwise it is a :class:BinarySampleSet with a BinarySampleSet | ommx.v1.Solution — single sample in the model’s original vartype.

Raises:

• ValueError — If method is not recognized, initial_state has wrong length or invalid values, max_iter is less than -1, or initial_state is an :class:ommx.v1.Solution that does not cover the instance’s used decision variables (or LocalSearch was constructed from a :class:BinaryModel, so there is no instance for the Solution to be interpreted against).

LocalSearchMethod [source]¶

class LocalSearchMethod(enum.StrEnum)

Strategy for picking which bit to flip at each local-search step.

Both variants only accept strictly improving flips; the difference is in how the next flip is chosen.

Attributes¶

• BEST

• FIRST

VarType [source]¶

class VarType(enum.StrEnum)

Attributes¶

• BINARY

• SPIN