ommx.adapter

ommx.adapter#

Attributes#

`PreconditionValue`
`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#

`AdapterApplicabilityReport`	Combined input-class and adapter-specific applicability result.
`AdapterPreconditionViolation`	One adapter-owned condition that an OMMX input class cannot express.
`ConstraintRef`	Constraint identity qualified by its independently scoped family.
`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(report: AdapterApplicabilityReport)#

Raised when an instance is not applicable to an adapter.

report: AdapterApplicabilityReport#

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 AdapterApplicabilityReport#

Combined input-class and adapter-specific applicability result.

adapter: str#

input_membership: InstanceClassMembershipReport#

property is_applicable: bool#

precondition_violations: tuple[AdapterPreconditionViolation, Ellipsis]#

preconditions_checked: bool#

class AdapterPreconditionViolation#

One adapter-owned condition that an OMMX input class cannot express.

actual: PreconditionValue = None#

condition: str#

constraint_refs: frozenset[ConstraintRef]#

description: str#

limit: PreconditionValue = None#

variable_ids: frozenset[int]#

class ConstraintRef#

Constraint identity qualified by its independently scoped family.

family: str#

id: int#

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) → AdapterApplicabilityReport#

Inspect applicability without mutating or preparing ommx_instance.

Adapter-specific preconditions run only after at least one complete input-class clause contains the instance. The hook receives an isolated copy so it cannot mutate the caller’s instance. Any explicitly transformed value is a different input and must be checked separately.

abstract decode(data: SolverOutput) → Solution#

abstract decode_to_sampleset(data: SamplerOutput) → SampleSet#

classmethod require_applicable(ommx_instance: Instance) → AdapterApplicabilityReport#: Return the report or raise AdapterNotApplicableError.

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

Abstractmethod:

Sample an OMMX instance.

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

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

Abstractmethod:

Solve an OMMX instance.

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.

INPUT_CLASS: ClassVar[InstanceClass | None] = None#

property sampler_input: SamplerInput#

Abstractmethod:

property solver_input: SolverInput#

Abstractmethod:

class SolverAdapter#

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