ommx.adapter

Attributes

SamplerInput
SamplerOutput
SolverInput
SolverOutput

Exceptions

InfeasibleDetected	Raised when the problem is proven to be infeasible.
NoSolutionReturned	Raised when no solution was returned.
UnboundedDetected	Raised when the problem is proven to be unbounded.

Classes

DiagnosticReport	Adapter diagnostic report convertible with dataclasses.asdict.
DiagnosticsSink	Receiver for adapter-defined diagnostics emitted during a solve.
SamplerAdapter	An abstract interface for OMMX Sampler Adapters, defining how samplers should be used with OMMX.
SolverAdapter	An abstract interface for OMMX Solver Adapters, defining how solvers should be used with OMMX.

Module Contents

exception InfeasibleDetected

Raised when the problem is proven to be infeasible.

This corresponds to Optimality.OPTIMALITY_INFEASIBLE and indicates that the mathematical model itself has no feasible solution. Should not be used when infeasibility cannot be proven (e.g., heuristic solvers).

exception NoSolutionReturned

Raised when no solution was returned.

This indicates that the solver did not return any solution (whether feasible or not) (e.g., due to time limits). This does not prove that the mathematical model itself is infeasible.

exception UnboundedDetected

Raised when the problem is proven to be unbounded.

This corresponds to Optimality.OPTIMALITY_UNBOUNDED and indicates that the mathematical model itself is unbounded. Should not be used when unboundedness cannot be proven (e.g., heuristic solvers).

class DiagnosticReport

Adapter diagnostic report convertible with dataclasses.asdict.

class DiagnosticsSink

Receiver for adapter-defined diagnostics emitted during a solve.

Adapters may call record while the backend solver is still running, including from backend callbacks. Sink implementations should keep record append-only, defer validation or serialization until after the solve, and preserve the order in which diagnostics are received.

A conforming sink must not raise from record. If recording fails, the sink should log the failure and return normally. If record does raise, that is a sink contract violation; adapters may let the exception propagate and do not need to recover from it.

record(diagnostic: DiagnosticReport) → None

Record one adapter-defined dataclass diagnostic report or event.

This method must not raise under normal sink failures. Custom sinks should log failures and return instead.

class SamplerAdapter(ommx_instance: Instance)

An abstract interface for OMMX Sampler Adapters, defining how samplers should be used with OMMX.

See the implementation guide for more details.

abstract decode(data: SolverOutput) → Solution

abstract decode_to_sampleset(data: SamplerOutput) → SampleSet

classmethod sample(ommx_instance: Instance) → SampleSet

Abstractmethod:

classmethod solve(ommx_instance: Instance, *, diagnostics: DiagnosticsSink | None = None) → Solution

Abstractmethod:

Solve an OMMX instance.

Run.log_solve owns the reserved diagnostics keyword and passes a sink to every adapter. Adapters may record adapter-defined dataclass diagnostics into the sink during the solve; leaving it empty means no diagnostics are stored. Adapters do not need to catch exceptions raised by a non-conforming diagnostics sink.

ADDITIONAL_CAPABILITIES: frozenset[AdditionalCapability]

property sampler_input: SamplerInput

Abstractmethod:

property solver_input: SolverInput

Abstractmethod:

class SolverAdapter(ommx_instance: Instance)

An abstract interface for OMMX Solver Adapters, defining how solvers should be used with OMMX.

See the implementation guide for more details.

Subclasses should set ADDITIONAL_CAPABILITIES to declare which non-standard constraint types they can handle. Standard constraints are always supported.

Available capabilities:

• AdditionalCapability.Indicator: binvar = 1 → f(x) <= 0

• AdditionalCapability.OneHot: exactly one of a set of binary variables is 1

• AdditionalCapability.Sos1: at most one of a set of variables is non-zero

The default is an empty set (standard constraints only). Subclasses must call super().__init__(ommx_instance) so that any constraint types the adapter does not support are automatically converted into regular constraints (Big-M for indicator / SOS1, linear equality for one-hot). Conversions mutate ommx_instance in place and are emitted at INFO level as tracing events from the Rust SDK; configure a Python OpenTelemetry TracerProvider before the first call to observe them via pyo3-tracing-opentelemetry.

abstract decode(data: SolverOutput) → Solution

classmethod solve(ommx_instance: Instance, *, diagnostics: DiagnosticsSink | None = None) → Solution

Abstractmethod:

Solve an OMMX instance.

Run.log_solve owns the reserved diagnostics keyword and passes a sink to every adapter. Adapters may record adapter-defined dataclass diagnostics into the sink during the solve; leaving it empty means no diagnostics are stored. Adapters do not need to catch exceptions raised by a non-conforming diagnostics sink.

ADDITIONAL_CAPABILITIES: frozenset[AdditionalCapability]

property solver_input: SolverInput

Abstractmethod:

SamplerInput

SamplerOutput

SolverInput

SolverOutput