ommx.adapter ============ .. py:module:: ommx.adapter Attributes ---------- .. autoapisummary:: ommx.adapter.PreconditionValue ommx.adapter.SamplerInput ommx.adapter.SamplerOutput ommx.adapter.SolverInput ommx.adapter.SolverOutput Exceptions ---------- .. autoapisummary:: ommx.adapter.AdapterNotApplicableError ommx.adapter.NoSolutionReturned ommx.adapter.UnboundedDetected Classes ------- .. autoapisummary:: ommx.adapter.AdapterApplicabilityReport ommx.adapter.AdapterPreconditionViolation ommx.adapter.ConstraintRef ommx.adapter.DiagnosticReport ommx.adapter.DiagnosticsSink ommx.adapter.SamplerAdapter ommx.adapter.SolverAdapter Module Contents --------------- .. py:exception:: AdapterNotApplicableError(report: AdapterApplicabilityReport) Raised when an instance is not applicable to an adapter. .. py:attribute:: report :type: AdapterApplicabilityReport .. py: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. .. py: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). .. py:class:: AdapterApplicabilityReport Combined input-class and adapter-specific applicability result. .. py:attribute:: adapter :type: str .. py:attribute:: input_membership :type: ommx.InstanceClassMembershipReport .. py:property:: is_applicable :type: bool .. py:attribute:: precondition_violations :type: tuple[AdapterPreconditionViolation, Ellipsis] .. py:attribute:: preconditions_checked :type: bool .. py:class:: AdapterPreconditionViolation One adapter-owned condition that an OMMX input class cannot express. .. py:attribute:: actual :type: PreconditionValue :value: None .. py:attribute:: condition :type: str .. py:attribute:: constraint_refs :type: frozenset[ConstraintRef] .. py:attribute:: description :type: str .. py:attribute:: limit :type: PreconditionValue :value: None .. py:attribute:: variable_ids :type: frozenset[int] .. py:class:: ConstraintRef Constraint identity qualified by its independently scoped family. .. py:attribute:: family :type: str .. py:attribute:: id :type: int .. py:class:: DiagnosticReport Adapter diagnostic report convertible with ``dataclasses.asdict``. .. py: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. .. py:method:: 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. .. py:class:: SamplerAdapter An abstract interface for OMMX Sampler Adapters, defining how samplers should be used with OMMX. See the `implementation guide `_ for more details. .. py:method:: check_applicability(ommx_instance: ommx.Instance) -> AdapterApplicabilityReport :classmethod: 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. .. py:method:: decode(data: SolverOutput) -> ommx.Solution :abstractmethod: .. py:method:: decode_to_sampleset(data: SamplerOutput) -> ommx.SampleSet :abstractmethod: .. py:method:: require_applicable(ommx_instance: ommx.Instance) -> AdapterApplicabilityReport :classmethod: Return the report or raise :class:`AdapterNotApplicableError`. .. py:method:: sample(ommx_instance: ommx.Instance, *, diagnostics: DiagnosticsSink | None = None) -> ommx.SampleSet :classmethod: :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. .. py:method:: solve(ommx_instance: ommx.Instance, *, diagnostics: DiagnosticsSink | None = None) -> ommx.Solution :classmethod: :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. .. py:attribute:: INPUT_CLASS :type: ClassVar[ommx.InstanceClass | None] :value: None .. py:property:: sampler_input :type: SamplerInput :abstractmethod: .. py:property:: solver_input :type: SolverInput :abstractmethod: .. py:class:: SolverAdapter An abstract interface for OMMX Solver Adapters, defining how solvers should be used with OMMX. See the `implementation guide `_ for more details. Subclasses declare ``INPUT_CLASS`` as the OMMX-defined structural class used by the first applicability condition. ``check_applicability`` does not mutate the input and combines class membership with the adapter's ``_check_preconditions`` hook. ``INPUT_CLASS`` describes only which exact inputs an adapter accepts; it does not prescribe how the subclass processes them. The base class never lowers or otherwise mutates the input instance. .. py:method:: check_applicability(ommx_instance: ommx.Instance) -> AdapterApplicabilityReport :classmethod: 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. .. py:method:: decode(data: SolverOutput) -> ommx.Solution :abstractmethod: .. py:method:: require_applicable(ommx_instance: ommx.Instance) -> AdapterApplicabilityReport :classmethod: Return the report or raise :class:`AdapterNotApplicableError`. .. py:method:: solve(ommx_instance: ommx.Instance, *, diagnostics: DiagnosticsSink | None = None) -> ommx.Solution :classmethod: :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. .. py:attribute:: INPUT_CLASS :type: ClassVar[ommx.InstanceClass | None] :value: None .. py:property:: solver_input :type: SolverInput :abstractmethod: .. py:data:: PreconditionValue .. py:data:: SamplerInput .. py:data:: SamplerOutput .. py:data:: SolverInput .. py:data:: SolverOutput