ommx.adapter

Attributes

SamplerInput
SamplerOutput
SolverInput
SolverOutput

Exceptions

AdapterNotApplicableError	Raised when an instance is not applicable to an adapter.
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 AdapterNotApplicableError(adapter: str, report: InstanceClassMembershipReport)

Raised when an instance is not applicable to an adapter.

adapter: str

report: InstanceClassMembershipReport

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

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

See the implementation guide for more details.

classmethod check_applicability(ommx_instance: Instance) → InstanceClassMembershipReport

Check INPUT_CLASS membership without mutation.

decode(data: SolverOutput) → Solution

Decode sampler output and return its best feasible solution.

abstract decode_to_sampleset(data: SamplerOutput) → SampleSet

classmethod recommended_preparation_policy() → PreparationPolicy

Return a fresh policy recommended for this Adapter's INPUT_CLASS.

The easy APIs apply it to an isolated copy. Advanced callers may edit and apply it explicitly before using a preparation-free API. This method itself neither prepares an instance nor guarantees applicability. The default policy is empty.

classmethod require_applicable(ommx_instance: Instance) → InstanceClassMembershipReport

Return the membership report or raise AdapterNotApplicableError.

classmethod sample(ommx_instance: Instance, *, diagnostics: DiagnosticsSink | None = None) → SampleSet

Prepare and sample an isolated copy of an OMMX instance.

The input ommx_instance is never modified. The copy is prepared for INPUT_CLASS with recommended_preparation_policy(), then passed to sample_without_preparation().

Run.log_sample owns the reserved diagnostics keyword and uses it the same way as Run.log_solve. None means diagnostics are disabled.

classmethod sample_without_preparation(ommx_instance: Instance, *, diagnostics: DiagnosticsSink | None = None) → SampleSet

Abstractmethod:

Sample an exact Adapter input without running Instance.prepare.

ommx_instance must belong to INPUT_CLASS. Implementations must reject non-members with AdapterNotApplicableError and must not prepare or otherwise modify the input instance.

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

Prepare and solve an isolated copy of an OMMX instance.

The input ommx_instance is never modified. The copy is prepared for INPUT_CLASS with recommended_preparation_policy(), then passed to solve_without_preparation().

Run.log_solve owns the reserved diagnostics keyword. When called with store_diagnostics=True, it passes a sink to the adapter and stores recorded diagnostics with the Solve entry. Adapters may record adapter-defined dataclass diagnostics into the sink during the solve; None means diagnostics are disabled. Adapters do not need to catch exceptions raised by a non-conforming diagnostics sink.

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

Return the best feasible result from sample_without_preparation().

INPUT_CLASS: ClassVar[InstanceClass]

Required condition for an exact Adapter input.

property sampler_input: SamplerInput

Abstractmethod:

property solver_input: SolverInput

Expose sampler_input through the SolverAdapter interface.

class SolverAdapter

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

See the implementation guide for more details.

Concrete subclasses define applicability with INPUT_CLASS. The easy solve() API prepares an isolated copy with the Adapter's recommended policy. Use solve_without_preparation() when the caller owns preparation and wants the Adapter to require an exact input without modifying it.

classmethod check_applicability(ommx_instance: Instance) → InstanceClassMembershipReport

Check INPUT_CLASS membership without mutation.

abstract decode(data: SolverOutput) → Solution

classmethod recommended_preparation_policy() → PreparationPolicy

Return a fresh policy recommended for this Adapter's INPUT_CLASS.

The easy APIs apply it to an isolated copy. Advanced callers may edit and apply it explicitly before using a preparation-free API. This method itself neither prepares an instance nor guarantees applicability. The default policy is empty.

classmethod require_applicable(ommx_instance: Instance) → InstanceClassMembershipReport

Return the membership report or raise AdapterNotApplicableError.

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

Prepare and solve an isolated copy of an OMMX instance.

The input ommx_instance is never modified. The copy is prepared for INPUT_CLASS with recommended_preparation_policy(), then passed to solve_without_preparation().

Run.log_solve owns the reserved diagnostics keyword. When called with store_diagnostics=True, it passes a sink to the adapter and stores recorded diagnostics with the Solve entry. Adapters may record adapter-defined dataclass diagnostics into the sink during the solve; None means diagnostics are disabled. Adapters do not need to catch exceptions raised by a non-conforming diagnostics sink.

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

Abstractmethod:

Solve an exact Adapter input without running Instance.prepare.

ommx_instance must belong to INPUT_CLASS. Implementations must reject non-members with AdapterNotApplicableError and must not prepare or otherwise modify the input instance.

INPUT_CLASS: ClassVar[InstanceClass]

Required condition for an exact Adapter input.

property solver_input: SolverInput

Abstractmethod:

SamplerInput

SamplerOutput

SolverInput

SolverOutput