qamomile.optimization.converter

Overview¶

Functions¶

binary_sampleset_to_ommx_samples [source]¶

def binary_sampleset_to_ommx_samples(binary_sampleset: BinarySampleSet) -> ommx.v1.Samples

Convert a BINARY sample set into an OMMX Samples container.

Each unique sample state is appended once with a list of sample IDs of length num_occurrences, so OMMX-side aggregation reflects the original shot counts without duplicating the underlying state. States with num_occurrences == 0 are skipped.

This is the canonical bridge from Qamomile’s :class:BinarySampleSet to OMMX’s :class:ommx.v1.Samples. It is the helper that :meth:MathematicalProblemConverter.decode and :meth:~qamomile.optimization.pce.PCEConverter.decode use to feed samples into :meth:ommx.v1.Instance.evaluate_samples for feasibility and original-objective evaluation.

Parameters:

Returns:

ommx.v1.Samples — ommx.v1.Samples: An OMMX Samples object with ommx.v1.Samples — sum(num_occurrences) sample IDs, where IDs sharing the same ommx.v1.Samples — state are grouped together. The returned object is empty when the ommx.v1.Samples — input has no samples.

Raises:

• ValueError — If binary_sampleset.vartype is not VarType.BINARY. SPIN sample sets must be converted first.

• ValueError — If the lengths of binary_sampleset.samples and binary_sampleset.num_occurrences are inconsistent (and, when present, binary_sampleset.energy as well).

normalize_problem_input [source]¶

def normalize_problem_input(
    instance: ommx.v1.Instance | BinaryModel,
) -> tuple[ommx.v1.Instance | None, VarType, BinaryModel]

Normalize a problem input into (stored_instance, original_vartype, spin_model).

Shared canonical entry point used by every converter that consumes a combinatorial optimization problem expressed either as an OMMX :class:ommx.v1.Instance or a Qamomile :class:BinaryModel. The :class:MathematicalProblemConverter base class and :class:~qamomile.optimization.pce.PCEConverter (which deliberately does not inherit from that base) both delegate to this helper so the OMMX deep-copy / to_hubo semantics live in exactly one place.

For OMMX inputs, the instance is deep-copied via a bytes round-trip before to_hubo is called: to_hubo mutates the instance it is called on (it appends slack decision variables for non-binary vars and absorbs constraints into the objective via the penalty method). Mutating the caller’s instance silently is surprising; copying first leaves the caller’s view untouched. The deep copy retains original-constraint metadata internally, so downstream evaluate_samples reports feasibility against the user’s original constraints, and slack bits added by to_hubo are reconstructed back into the original decision variables (e.g., integers rebuilt from log-encoded slack bits) by evaluate_samples automatically.

to_hubo is used instead of to_qubo so that both purely quadratic (QUBO) and higher-order (HUBO) instances are handled uniformly. For quadratic-only instances the two paths produce equivalent optimization problems (same coefficients and vartype).

Parameters:

Returns:

ommx.v1.Instance | None — tuple[ommx.v1.Instance | None, VarType, BinaryModel]: A triple VarType — (stored_instance, original_vartype, spin_model). BinaryModel — * stored_instance: the deep-copied Instance for OMMX inputs (post to_hubo), or None for BinaryModel inputs. tuple[ommx.v1.Instance | None, VarType, BinaryModel] — * original_vartype: the declared vartype of the input — used by converters’ decode paths to return results in the caller’s preferred representation. tuple[ommx.v1.Instance | None, VarType, BinaryModel] — * spin_model: the problem rewritten in SPIN form, which is the natural domain for sign rounding and Pauli encoding.

Raises:

• TypeError — If instance is neither an :class:ommx.v1.Instance nor a :class:BinaryModel.

Classes¶

MathematicalProblemConverter [source]¶

class MathematicalProblemConverter(abc.ABC)

Constructor¶

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

Methods¶

decode¶

def decode(self, samples: SampleResult[list[int]]) -> BinarySampleSet | ommx.v1.SampleSet

Decode quantum measurement results.

The return type tracks the input that built this converter:

• Built from an :class:ommx.v1.Instance — returns an :class:ommx.v1.SampleSet evaluated against the original (un-penalized) instance, so feasibility, objective, and per-constraint violations are available through OMMX’s own API (.summary, .summary_with_constraints, .best_feasible, .feasible, .objectives).

• Built from a :class:BinaryModel — returns a :class:BinarySampleSet with samples in the model’s original vartype (BINARY 0/1 or SPIN ±1), energies, and shot counts.

Parameters:

Returns:

BinarySampleSet | ommx.v1.SampleSet — BinarySampleSet | ommx.v1.SampleSet: see method description.

See Also:

:meth:decode_to_binary_sampleset: always returns a :class:BinarySampleSet. Use it when you need the QUBO-domain (penalty-included) energy — e.g. to drive a classical optimizer that must penalize infeasibility.

Example:

>>> # OMMX in → OMMX out
>>> converter = QAOAConverter(ommx_instance)
>>> exe = converter.transpile(QiskitTranspiler(), p=2)
>>> result = exe.sample(QiskitTranspiler().executor(),
...                     shots=1024,
...                     bindings={"gammas": gs, "betas": bs}).result()
>>> sample_set = converter.decode(result)
>>> sample_set.best_feasible.objective

decode_to_binary_sampleset¶

def decode_to_binary_sampleset(self, samples: SampleResult[list[int]]) -> BinarySampleSet

Decode samples into a :class:BinarySampleSet.

Always returns a :class:BinarySampleSet, regardless of whether this converter was constructed with an :class:ommx.v1.Instance or a :class:BinaryModel. Use this when you need:

• The QUBO-domain energy (penalty-included), e.g. as the cost driving a classical optimizer like COBYLA — :meth:decode on OMMX-backed converters returns the un-penalized OMMX objective which won’t penalize infeasibility.

• The per-state samples / num_occurrences / vartype views from :class:BinarySampleSet.

For most usage — feasibility, original-objective evaluation, per-constraint diagnostics — prefer the polymorphic :meth:decode, which returns an :class:ommx.v1.SampleSet for OMMX-backed converters.

Parameters:

Returns:

BinarySampleSet — keyed by the SPIN model’s original variable BinarySampleSet — indices (the QUBO variable IDs for OMMX-backed converters) BinarySampleSet — in the converter’s original_vartype — BINARY for BinarySampleSet — OMMX-backed converters, the :class:BinaryModel’s declared BinarySampleSet — vartype otherwise.

get_cost_hamiltonian¶

def get_cost_hamiltonian(self) -> qm_o.Hamiltonian

Construct the cost Hamiltonian.

Subclasses must implement this method to build the appropriate Hamiltonian for their specific algorithm (e.g., Pauli-Z for QAOA, QRAC-encoded for QRAO). Oracle-based converters that do not use a cost Hamiltonian (e.g., GASConverter) should raise NotImplementedError.

Returns:

qm_o.Hamiltonian — qm_o.Hamiltonian: The cost Hamiltonian.

Raises:

• NotImplementedError — If the converter does not expose a cost Hamiltonian.

SampleResult [source]¶

class SampleResult(Generic[T])

Result of a sample() execution.

Contains results as a list of (value, count) tuples.

Example:

result.results  # [(0.25, 500), (0.75, 500)]

Constructor¶

def __init__(self, results: list[tuple[T, int]], shots: int) -> None

Attributes¶

• results: list[tuple[T, int]] List of (value, count) tuples.

• shots: int Total number of shots executed.

Methods¶

most_common¶

def most_common(self, n: int = 1) -> list[tuple[T, int]]

Return the n most common results.

Parameters:

Returns:

list[tuple[T, int]] — List of (result, count) tuples sorted by count descending.

probabilities¶

def probabilities(self) -> list[tuple[T, float]]

Return probability distribution over results.

Returns:

list[tuple[T, float]] — List of (value, probability) tuples.