ommx_python_mip_adapter.adapter

ommx_python_mip_adapter.adapter#

Classes#

OMMXPythonMIPAdapter

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

Module Contents#

class OMMXPythonMIPAdapter(ommx_instance: Instance, *, relax: bool = False, solver_name: str = mip.CBC, solver: mip.Solver | None = None, verbose: bool = False)#

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

See the Adapter implementation tutorial for the complete implementation contract and reference implementation.

Subclasses declare INPUT_CLASS as the OMMX-defined structural class of exact inputs they can encode. Membership in that class is the complete applicability condition: check_applicability only checks membership and does not mutate the input. A subclass should call require_applicable before constructing backend input.

The easy solve() API prepares an isolated copy with the Adapter’s recommended policy. Use solve_without_preparation() when the caller has prepared an exact input explicitly and wants the Adapter to require INPUT_CLASS membership without applying preparation.

When encoding OMMX decision variables, use ommx_instance.used_decision_variables rather than the complete decision variable table. Backend-only auxiliary variables may be added separately. Preserve the correspondence between each used OMMX variable ID and its backend representation. Decoding must recover a value for every used OMMX variable, construct a ommx.State, and evaluate it against an unchanged ommx.Instance snapshot that is mathematically identical to the exact input encoded for the backend. The Instance owns population of fixed, dependent, and irrelevant variables and construction of the final ommx.Solution.

classmethod check_applicability(ommx_instance: Instance) → InstanceClassMembershipReport#

Check INPUT_CLASS membership without mutation.

decode(data: mip.Model) → Solution#

Convert optimized Python-MIP model and ommx.Instance to ommx.Solution.

This method is intended to be used if the model has been acquired with solver_input for futher adjustment of the solver parameters, and separately optimizing the model.

Note that alterations to the model may make the decoding process incompatible – decoding will only work if the model still describes effectively the same problem as the OMMX instance used to create the adapter.

When creating the solution, this method reflects the relax flag used in this adapter’s constructor. The solution’s relaxation metadata will be set _only_ if relax=True was passed to the constructor. There is no way for this adapter to get relaxation information from Python-MIP directly. If relaxing the model separately after obtaining it with solver_input, you must set solution.relaxation yourself if you care about this value.

Backend optimality is mapped through the instance’s output-objective semantics. It remains unspecified when active-formulation optimality does not transport to that objective.

Examples#

>>> from ommx import Instance, DecisionVariable
>>> from ommx_python_mip_adapter import OMMXPythonMIPAdapter

>>> p = [10, 13, 18, 32, 7, 15]
>>> w = [11, 15, 20, 35, 10, 33]
>>> x = [DecisionVariable.binary(i) for i in range(6)]
>>> instance = Instance.from_components(
...     decision_variables=x,
...     objective=sum(p[i] * x[i] for i in range(6)),
...     constraints={0: sum(w[i] * x[i] for i in range(6)) <= 47},
...     sense=Sense.Maximize,
... )

>>> adapter = OMMXPythonMIPAdapter(instance)
>>> model = adapter.solver_input
>>> # ... some modification of model's parameters
>>> model.optimize()
<OptimizationStatus.OPTIMAL: 0>

>>> solution = adapter.decode(model)
>>> solution.objective
42.0
decode_to_state(data: mip.Model) → State#

Create an ommx.State from an optimized Python-MIP Model.

Examples#

The following example of solving an unconstrained linear optimization problem with x1 as the objective function.

>>> from ommx_python_mip_adapter import OMMXPythonMIPAdapter
>>> from ommx import Instance, DecisionVariable

>>> x1 = DecisionVariable.integer(1, lower=0, upper=5)
>>> ommx_instance = Instance.from_components(
...     decision_variables=[x1],
...     objective=x1,
...     constraints={},
...     sense=Sense.Minimize,
... )
>>> adapter = OMMXPythonMIPAdapter(ommx_instance)
>>> model = adapter.solver_input
>>> model.optimize()
<OptimizationStatus.OPTIMAL: 0>

>>> ommx_state = adapter.decode_to_state(model)
>>> ommx_state.entries
{1: 0.0}
classmethod recommended_preparation_policy() → PreparationPolicy#

Recommend lowering special constraints before using Python-MIP.

Python-MIP currently accepts only regular constraints through this adapter. The recommendation therefore lowers the special-constraint families currently understood by OMMX. The easy API applies a fresh policy to an isolated copy; callers may instead edit and apply one before invoking solve_without_preparation().

classmethod require_applicable(ommx_instance: Instance) → InstanceClassMembershipReport#

Return the membership report or raise AdapterNotApplicableError.

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

Solve the given ommx.Instance using Python-MIP, returning an ommx.Solution.

The input instance is not modified. An isolated copy is prepared with the recommended Python-MIP policy before preparation-free execution.

Parameters:

  • ommx_instance – The ommx.Instance to prepare and solve.

  • relax – If True, relax all integer variables to continuous variables by using the relax parameter in Python-MIP’s Model.optimize() <https://docs.python-mip.com/en/latest/classes.html#mip.Model.optimize>.

  • verbose – If True, enable Python-MIP’s verbose mode

Examples#

KnapSack Problem

>>> from ommx import Instance, DecisionVariable
>>> from ommx_python_mip_adapter import OMMXPythonMIPAdapter

>>> p = [10, 13, 18, 32, 7, 15]
>>> w = [11, 15, 20, 35, 10, 33]
>>> x = [DecisionVariable.binary(i) for i in range(6)]
>>> instance = Instance.from_components(
...     decision_variables=x,
...     objective=sum(p[i] * x[i] for i in range(6)),
...     constraints={0: sum(w[i] * x[i] for i in range(6)) <= 47},
...     sense=Sense.Maximize,
... )

Solve it

>>> solution = OMMXPythonMIPAdapter.solve(instance)

Check output

>>> sorted([(id, value) for id, value in solution.state.entries.items()])
[(0, 1.0), (1, 0.0), (2, 0.0), (3, 1.0), (4, 0.0), (5, 0.0)]
>>> solution.feasible
True
>>> assert solution.optimality == Solution.OPTIMAL

p[0] + p[3] = 42
w[0] + w[3] = 46 <= 47

>>> solution.objective
42.0
>>> solution.get_constraint_value(0)
-1.0

Infeasible Problem

>>> from ommx import Instance, DecisionVariable
>>> from ommx_python_mip_adapter import OMMXPythonMIPAdapter

>>> x = DecisionVariable.integer(0, upper=3, lower=0)
>>> instance = Instance.from_components(
...     decision_variables=[x],
...     objective=x,
...     constraints={0: x >= 4},
...     sense=Sense.Maximize,
... )

>>> OMMXPythonMIPAdapter.solve(instance)
Traceback (most recent call last):
    ...
ommx.InfeasibleDetected: Model was infeasible

Unbounded Problem

>>> from ommx import Instance, DecisionVariable
>>> from ommx_python_mip_adapter import OMMXPythonMIPAdapter

>>> x = DecisionVariable.integer(0, lower=0)
>>> instance = Instance.from_components(
...     decision_variables=[x],
...     objective=x,
...     constraints={},
...     sense=Sense.Maximize,
... )

>>> OMMXPythonMIPAdapter.solve(instance)
Traceback (most recent call last):
    ...
ommx.adapter.UnboundedDetected: Model was unbounded

Dual variable

>>> from ommx import Instance, DecisionVariable
>>> from ommx_python_mip_adapter import OMMXPythonMIPAdapter

>>> x = DecisionVariable.continuous(0, lower=0, upper=1)
>>> y = DecisionVariable.continuous(1, lower=0, upper=1)
>>> instance = Instance.from_components(
...     decision_variables=[x, y],
...     objective=x + y,
...     constraints={0: x + y <= 1},
...     sense=Sense.Maximize,
... )

>>> solution = OMMXPythonMIPAdapter.solve(instance)
>>> solution.get_dual_variable(0)
1.0
classmethod solve_without_preparation(ommx_instance: Instance, relax: bool = False, verbose: bool = False, *, diagnostics: DiagnosticsSink | None = None) → Solution#

Solve an exact Python-MIP Adapter input without preparing it.

INPUT_CLASS: ClassVar[InstanceClass]#

Required condition for an exact Adapter input.

property solver_input: mip.Model#

The Python-MIP model generated from this OMMX instance

Contents