ommx-python-mip-adapter 0.0.2__tar.gz → 0.1.0__tar.gz

ommx_python_mip_adapter-0.1.0/.github/workflows/docs.yml

@@ -0,0 +1,72 @@
+name: Documents
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+  workflow_dispatch:
+
+# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+# Allow one concurrent deployment
+concurrency:
+  group: "pages"
+  cancel-in-progress: true
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.8"
+      
+      - name: Install dependencies
+        run: |
+          python -m pip install ".[dev]"
+      
+      - name: Build Python documentation
+        run: |
+          sphinx-build -b html ./docs/source ./docs/build
+
+      - name: Upload HTML
+        uses: actions/upload-artifact@v4
+        with:
+          name: docs
+          path: ./docs/build
+          retention-days: 30
+
+  deploy:
+    if: github.ref == 'refs/heads/main'
+    needs: build
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    steps:
+      - name: Download HTML
+        uses: actions/download-artifact@v4
+        with:
+          name: docs
+          path: .
+
+      - name: Configure GitHub Pages
+        uses: actions/configure-pages@v4
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: "."
+
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

{ommx_python_mip_adapter-0.0.2 → ommx_python_mip_adapter-0.1.0}/.github/workflows/test_and_lint.yml

@@ -28,7 +28,7 @@ jobs:
 
       - name: Run Tests
         run: |
-          python -m pytest
+          python -m pytest --doctest-modules -vv
 
   lint:
     runs-on: ubuntu-latest
@@ -50,5 +50,26 @@ jobs:
 
       - name: Lint
         run: |
-          python -m mypy ./ommx_python_mip_adapter
           python -m pyright ./ommx_python_mip_adapter
+
+  markdown-code-runner:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.8", "3.9", "3.10", "3.11", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install Dependencies
+        run: |
+          python -m pip install ".[dev]"
+
+      - name: Lint
+        run: |
+          markdown-code-runner --verbose README.md

ommx_python_mip_adapter-0.1.0/PKG-INFO

@@ -0,0 +1,104 @@
+Metadata-Version: 2.1
+Name: ommx_python_mip_adapter
+Version: 0.1.0
+Summary: An adapter for the Python-MIP from/to OMMX.
+Author-email: "Jij Inc." <info@j-ij.com>
+Project-URL: Repository, https://github.com/Jij-Inc/ommx-python-mip-adapter
+Project-URL: Issues, https://github.com/Jij-Inc/ommx-python-mip-adapter/issues
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: License :: OSI Approved :: MIT License
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE-APACHE
+License-File: LICENSE-MIT
+Requires-Dist: ommx<0.2.0,>=0.1.1
+Requires-Dist: mip
+Provides-Extra: dev
+Requires-Dist: markdown-code-runner; extra == "dev"
+Requires-Dist: mypy; extra == "dev"
+Requires-Dist: numpy; extra == "dev"
+Requires-Dist: pyright; extra == "dev"
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: sphinx; extra == "dev"
+Requires-Dist: sphinx_rtd_theme; extra == "dev"
+Requires-Dist: sphinx_fontawesome; extra == "dev"
+Requires-Dist: sphinx-autoapi; extra == "dev"
+
+OMMX adaptor for Python-MIP
+============================
+![PyPI - Version](https://img.shields.io/pypi/v/ommx-python-mip-adapter)
+
+This package provides an adaptor for the [Python-MIP](https://www.python-mip.com/) from/to [OMMX](https://github.com/Jij-Inc/ommx)
+
+Python-MIP as a solver in OMMX toolchain
+-----------------------------------------
+```mermaid
+sequenceDiagram
+    participant O as Other OMMX toolchain
+    participant A as Adapter
+    participant P as Python-MIP
+    O->>A: ommx::Instance and Parameters for Python-MIP;
+    A->>P: Translate into Python-MIP input
+    P->>P: Solve with CBC, Gurobi, or other solvers
+    P->>A: Solution
+    A->>O: ommx:Solution
+```
+
+Python-MIP as a user interface to create OMMX instance
+-------------------------------------------------------
+TBW
+
+Usage
+======
+`ommx-python-mip-adapter` can be installed from PyPI as follows:
+
+```bash
+pip install ommx-python-mip-adapter
+```
+
+Python-MIP can be used through `ommx-python-mip-adapter` by using the following:
+
+```python markdown-code-runner
+import ommx_python_mip_adapter as adapter
+from ommx.v1.decision_variables_pb2 import DecisionVariable, Bound
+from ommx.v1.instance_pb2 import Instance
+from ommx.v1.function_pb2 import Function
+from ommx.v1.linear_pb2 import Linear
+from ommx.v1.solution_pb2 import SolutionList
+
+ommx_instance = Instance(
+    decision_variables=[
+        DecisionVariable(
+            id=1,
+            kind=DecisionVariable.KIND_INTEGER,
+            bound=Bound(lower=0, upper=5),
+        ),
+    ],
+    objective=Function(
+        linear=Linear(
+            terms=[Linear.Term(id=1, coefficient=1)]
+        ),
+    ),
+)
+ommx_instance_bytes = ommx_instance.SerializeToString()
+
+# Convert from `ommx.v1.Instance` to `mip.Model`
+model = adapter.instance_to_model(ommx_instance_bytes)
+model.optimize()
+# Create `ommx.v1.SolutionList` from Optimized `mip.Model`
+ommx_solutions_bytes = adapter.model_to_solution(
+    model, ommx_instance_bytes
+)
+
+print(SolutionList.FromString(ommx_solutions_bytes))
+```
+
+Reference
+==============
+- [OMMX-Python-MIP-Adapter API Reference](https://jij-inc.github.io/ommx-python-mip-adapter/index.html)

ommx_python_mip_adapter-0.1.0/README.md

@@ -0,0 +1,72 @@
+OMMX adaptor for Python-MIP
+============================
+![PyPI - Version](https://img.shields.io/pypi/v/ommx-python-mip-adapter)
+
+This package provides an adaptor for the [Python-MIP](https://www.python-mip.com/) from/to [OMMX](https://github.com/Jij-Inc/ommx)
+
+Python-MIP as a solver in OMMX toolchain
+-----------------------------------------
+```mermaid
+sequenceDiagram
+    participant O as Other OMMX toolchain
+    participant A as Adapter
+    participant P as Python-MIP
+    O->>A: ommx::Instance and Parameters for Python-MIP;
+    A->>P: Translate into Python-MIP input
+    P->>P: Solve with CBC, Gurobi, or other solvers
+    P->>A: Solution
+    A->>O: ommx:Solution
+```
+
+Python-MIP as a user interface to create OMMX instance
+-------------------------------------------------------
+TBW
+
+Usage
+======
+`ommx-python-mip-adapter` can be installed from PyPI as follows:
+
+```bash
+pip install ommx-python-mip-adapter
+```
+
+Python-MIP can be used through `ommx-python-mip-adapter` by using the following:
+
+```python markdown-code-runner
+import ommx_python_mip_adapter as adapter
+from ommx.v1.decision_variables_pb2 import DecisionVariable, Bound
+from ommx.v1.instance_pb2 import Instance
+from ommx.v1.function_pb2 import Function
+from ommx.v1.linear_pb2 import Linear
+from ommx.v1.solution_pb2 import SolutionList
+
+ommx_instance = Instance(
+    decision_variables=[
+        DecisionVariable(
+            id=1,
+            kind=DecisionVariable.KIND_INTEGER,
+            bound=Bound(lower=0, upper=5),
+        ),
+    ],
+    objective=Function(
+        linear=Linear(
+            terms=[Linear.Term(id=1, coefficient=1)]
+        ),
+    ),
+)
+ommx_instance_bytes = ommx_instance.SerializeToString()
+
+# Convert from `ommx.v1.Instance` to `mip.Model`
+model = adapter.instance_to_model(ommx_instance_bytes)
+model.optimize()
+# Create `ommx.v1.SolutionList` from Optimized `mip.Model`
+ommx_solutions_bytes = adapter.model_to_solution(
+    model, ommx_instance_bytes
+)
+
+print(SolutionList.FromString(ommx_solutions_bytes))
+```
+
+Reference
+==============
+- [OMMX-Python-MIP-Adapter API Reference](https://jij-inc.github.io/ommx-python-mip-adapter/index.html)

ommx_python_mip_adapter-0.1.0/docs/source/conf.py

@@ -0,0 +1,50 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# For the full list of built-in configuration values, see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+import sphinx_rtd_theme
+import sphinx_fontawesome
+
+# -- Project information -----------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
+
+project = 'ommx-python-mip-adapter'
+copyright = '2024, Jij Inc.'
+author = 'Jij Inc.'
+
+version = '0.1.0'
+release = '0.1.0'
+
+# -- General configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+
+extensions = [
+    'sphinx.ext.autodoc', 
+    'sphinx.ext.napoleon', 
+    'sphinx_rtd_theme', 
+    'sphinx_fontawesome', 
+    'autoapi.extension',
+]
+source_suffix = {
+    '.rst': 'restructuredtext',
+    '.md': 'markdown',
+}
+
+templates_path = ['_templates']
+language = 'en'
+exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
+
+# -- Options for HTML output -------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
+
+html_theme = "sphinx_rtd_theme"
+html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
+html_show_sourcelink = False
+html_static_path = ['_static']
+
+# -- AutoAPI settings --------------------------------------------------------
+# https://sphinx-autoapi.readthedocs.io/en/latest/reference/config.html#event-autoapi-skip-member
+
+autoapi_dirs = ['../../ommx_python_mip_adapter']
+autoapi_member_order = 'groupwise'

ommx_python_mip_adapter-0.1.0/docs/source/index.rst

@@ -0,0 +1,20 @@
+.. ommx-python-mip-adapter documentation master file, created by
+   sphinx-quickstart on Mon Apr 22 14:29:19 2024.
+   You can adapt this file completely to your liking, but it should at least
+   contain the root `toctree` directive.
+
+Welcome to ommx-python-mip-adapter's documentation!
+===================================================
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents:
+
+
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`

ommx_python_mip_adapter-0.1.0/ommx_python_mip_adapter/__init__.py

@@ -0,0 +1,9 @@
+from ommx_python_mip_adapter.adapter import (
+    instance_to_model,
+    model_to_solution,
+)
+
+__all__ = [
+    "instance_to_model",
+    "model_to_solution",
+]

{ommx_python_mip_adapter-0.0.2 → ommx_python_mip_adapter-0.1.0}/ommx_python_mip_adapter/_version.py

@@ -12,5 +12,5 @@ __version__: str
 __version_tuple__: VERSION_TUPLE
 version_tuple: VERSION_TUPLE
 
-__version__ = version = '0.0.2'
-__version_tuple__ = version_tuple = (0, 0, 2)
+__version__ = version = '0.1.0'
+__version_tuple__ = version_tuple = (0, 1, 0)

ommx_python_mip_adapter-0.1.0/ommx_python_mip_adapter/adapter.py

@@ -0,0 +1,262 @@
+import typing as tp
+
+import mip
+
+from ommx.v1.constraint_pb2 import Constraint
+from ommx.v1.decision_variables_pb2 import DecisionVariable
+from ommx.v1.function_pb2 import Function
+from ommx.v1.instance_pb2 import Instance
+from ommx.v1.solution_pb2 import Solution, SolutionList
+
+from ommx_python_mip_adapter.exception import OMMXPythonMIPAdapterError
+
+
+class PythonMIPBuilder:
+    def __init__(
+        self,
+        ommx_instance_bytes: bytes,
+        *,
+        sense: str = mip.MINIMIZE,
+        solver_name: str = mip.CBC,
+        solver: tp.Optional[mip.Solver] = None,
+    ):
+        try:
+            self._ommx_instance = Instance.FromString(ommx_instance_bytes)
+        except Exception as e:
+            raise OMMXPythonMIPAdapterError(
+                "Invalid `ommx_instance_bytes` as ommx.v1.Instance."
+            ) from e
+
+        self._model = mip.Model(
+            sense=sense,
+            solver_name=solver_name,
+            solver=solver,
+        )
+
+
+    def _set_decision_variables(self):
+        for var in self._ommx_instance.decision_variables:
+            if var.kind == DecisionVariable.KIND_BINARY:
+                self._model.add_var(
+                    name=str(var.id),
+                    var_type=mip.BINARY,
+                )
+            elif var.kind == DecisionVariable.KIND_INTEGER:
+                self._model.add_var(
+                    name=str(var.id),
+                    var_type=mip.INTEGER,
+                    lb=var.bound.lower,    # type: ignore
+                    ub=var.bound.upper,    # type: ignore
+                )
+            elif var.kind == DecisionVariable.KIND_CONTINUOUS:
+                self._model.add_var(
+                    name=str(var.id),
+                    var_type=mip.CONTINUOUS,
+                    lb=var.bound.lower,    # type: ignore
+                    ub=var.bound.upper,    # type: ignore
+                )
+            else:
+                raise OMMXPythonMIPAdapterError(
+                    f"Not supported decision variable kind: "
+                    f"id: {var.id}, kind: {var.kind}"
+                )
+    
+    
+    def _make_linear_expr(
+        self,
+        ommx_function: Function,
+    ) -> mip.LinExpr:        
+        ommx_linear = ommx_function.linear
+
+        return mip.xsum(
+            term.coefficient * self._model.vars[str(term.id)] # type: ignore
+            for term in ommx_linear.terms
+        ) + ommx_linear.constant # type: ignore
+
+            
+    def _set_objective_function(self):
+        ommx_objective = self._ommx_instance.objective
+
+        if ommx_objective.HasField("constant"):
+            self._model.objective = ommx_objective.constant    # type: ignore
+        elif ommx_objective.HasField("linear"):
+            self._model.objective = self._make_linear_expr(ommx_objective)
+        else:
+            raise OMMXPythonMIPAdapterError(
+                "The objective function must be either `constant` or `linear`."
+            )
+
+
+    def _set_constraints(self):
+        ommx_constraints = self._ommx_instance.constraints
+
+        for constraint in ommx_constraints:
+            if not constraint.function.HasField("linear"):
+                raise OMMXPythonMIPAdapterError(
+                    f"Only linear constraints are supported: "
+                    f"id: {constraint.id}, "
+                    f"type: {constraint.function.WhichOneof('function')}"
+                )
+
+            lin_expr = self._make_linear_expr(constraint.function)
+
+            if constraint.equality == Constraint.EQUALITY_EQUAL_TO_ZERO:
+                constr_expr = (lin_expr == 0)
+            elif (constraint.equality == Constraint.EQUALITY_LESS_THAN_OR_EQUAL_TO_ZERO):
+                constr_expr = (lin_expr <= 0)    # type: ignore
+            else:
+                raise OMMXPythonMIPAdapterError(
+                    f"Not supported constraint equality: "
+                    f"id: {constraint.id}, equality: {constraint.equality}"
+                )
+            
+            self._model.add_constr(constr_expr, name=str(constraint.id))
+
+
+    def build(self) -> mip.Model:
+        self._set_decision_variables()
+        self._set_objective_function()
+        self._set_constraints()
+
+        return self._model
+
+
+def instance_to_model(
+    ommx_instance_bytes: bytes,
+    *,
+    sense: str = mip.MINIMIZE,
+    solver_name: str = mip.CBC,
+    solver: tp.Optional[mip.Solver] = None,
+) -> mip.Model:
+    """
+    The function to convert ommx.v1.Instance to Python-MIP Model.
+
+    Args:
+        ommx_instance_bytes (bytes): Serialized ommx.v1.Instance.
+        sense (str): mip.MINIMIZE or mip.MAXIMIZE. 
+        solver_name (str): mip.CBC or mip.GUROBI. Searches for which solver is available if not informed.
+        solver (mip.Solver): if this argument is provided, solver_name will be ignored.
+
+    Returns:
+        mip.Model: Python-MIP Model converted from ommx.v1.Instance.
+
+    Raises:
+        OMMXPythonMIPAdapterError: If converting is not possible.
+
+    Examples:
+        The following example of solving an unconstrained linear optimization problem with x1 as the objective function.
+
+        >>> import ommx_python_mip_adapter as adapter
+        >>> from ommx.v1.decision_variables_pb2 import DecisionVariable, Bound
+        >>> from ommx.v1.instance_pb2 import Instance
+        >>> from ommx.v1.function_pb2 import Function
+        >>> from ommx.v1.linear_pb2 import Linear
+        >>> from ommx.v1.solution_pb2 import SolutionList
+        >>> ommx_instance = Instance(
+        ...     decision_variables=[
+        ...         DecisionVariable(
+        ...             id=1,
+        ...             kind=DecisionVariable.KIND_INTEGER,
+        ...             bound=Bound(lower=0, upper=5),
+        ...         ),
+        ...     ],
+        ...     objective=Function(
+        ...         linear=Linear(
+        ...             terms=[Linear.Term(id=1, coefficient=1)]
+        ...         ),
+        ...     ),
+        ... )
+        >>> ommx_instance_bytes = ommx_instance.SerializeToString()
+        >>> model = adapter.instance_to_model(ommx_instance_bytes)
+        >>> model.optimize()
+        <OptimizationStatus.OPTIMAL: 0>
+        >>> ommx_solutions_bytes = adapter.model_to_solution(
+        ...     model, ommx_instance_bytes
+        ... )
+        >>> SolutionList.FromString(ommx_solutions_bytes).solutions[0].entries
+        {1: 0.0}
+    """
+    builder = PythonMIPBuilder(
+        ommx_instance_bytes,
+        sense=sense,
+        solver_name=solver_name,
+        solver=solver,
+    )
+    return builder.build()
+
+
+def model_to_solution(
+    model: mip.Model,
+    ommx_instance_bytes: bytes,
+) -> bytes:
+    """
+    The function to create ommx.v1.SolutionList from optimized Python-MIP Model.
+
+    Args:
+        model (mip.Model): Optimized Python-MIP Model.
+        ommx_instance_bytes (bytes): Serialized ommx.v1.Instance.
+
+    Returns:
+        bytes: Serialized ommx.v1.SolutionList
+
+    Raises:
+        OMMXPythonMIPAdapterError: When ommx.v1.SolutionList cannot be created.
+
+    Examples:
+        The following example of solving an unconstrained linear optimization problem with x1 as the objective function.
+
+        >>> import ommx_python_mip_adapter as adapter
+        >>> from ommx.v1.decision_variables_pb2 import DecisionVariable, Bound
+        >>> from ommx.v1.instance_pb2 import Instance
+        >>> from ommx.v1.function_pb2 import Function
+        >>> from ommx.v1.linear_pb2 import Linear
+        >>> from ommx.v1.solution_pb2 import SolutionList
+        >>> ommx_instance = Instance(
+        ...     decision_variables=[
+        ...         DecisionVariable(
+        ...             id=1,
+        ...             kind=DecisionVariable.KIND_INTEGER,
+        ...             bound=Bound(lower=0, upper=5),
+        ...         ),
+        ...     ],
+        ...     objective=Function(
+        ...         linear=Linear(
+        ...             terms=[Linear.Term(id=1, coefficient=1)]
+        ...         ),
+        ...     ),
+        ... )
+        >>> ommx_instance_bytes = ommx_instance.SerializeToString()
+        >>> model = adapter.instance_to_model(ommx_instance_bytes)
+        >>> model.optimize()
+        <OptimizationStatus.OPTIMAL: 0>
+        >>> ommx_solutions_bytes = adapter.model_to_solution(
+        ...     model, ommx_instance_bytes
+        ... )
+        >>> SolutionList.FromString(ommx_solutions_bytes).solutions[0].entries
+        {1: 0.0}
+    """
+    if not (
+        model.status == mip.OptimizationStatus.OPTIMAL
+        or model.status == mip.OptimizationStatus.FEASIBLE
+    ):
+        raise OMMXPythonMIPAdapterError(
+            "`model.status` must be `OPTIMAL` or `FEASIBLE`."
+        )
+
+    try:
+        ommx_instance = Instance.FromString(ommx_instance_bytes)
+    except Exception as e:
+        raise OMMXPythonMIPAdapterError(
+            "Invalid `ommx_instance_bytes` as ommx.v1.Instance."
+        ) from e
+
+    return SolutionList(
+        solutions=[
+            Solution(
+                entries={
+                    var.id: model.var_by_name(str(var.id)).x    # type: ignore
+                    for var in ommx_instance.decision_variables
+                }
+            )
+        ]
+    ).SerializeToString()

ommx_python_mip_adapter-0.1.0/ommx_python_mip_adapter/exception.py

@@ -0,0 +1,2 @@
+class OMMXPythonMIPAdapterError(Exception):
+    pass

ommx_python_mip_adapter-0.1.0/ommx_python_mip_adapter.egg-info/PKG-INFO

@@ -0,0 +1,104 @@
+Metadata-Version: 2.1
+Name: ommx_python_mip_adapter
+Version: 0.1.0
+Summary: An adapter for the Python-MIP from/to OMMX.
+Author-email: "Jij Inc." <info@j-ij.com>
+Project-URL: Repository, https://github.com/Jij-Inc/ommx-python-mip-adapter
+Project-URL: Issues, https://github.com/Jij-Inc/ommx-python-mip-adapter/issues
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: License :: OSI Approved :: MIT License
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE-APACHE
+License-File: LICENSE-MIT
+Requires-Dist: ommx<0.2.0,>=0.1.1
+Requires-Dist: mip
+Provides-Extra: dev
+Requires-Dist: markdown-code-runner; extra == "dev"
+Requires-Dist: mypy; extra == "dev"
+Requires-Dist: numpy; extra == "dev"
+Requires-Dist: pyright; extra == "dev"
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: sphinx; extra == "dev"
+Requires-Dist: sphinx_rtd_theme; extra == "dev"
+Requires-Dist: sphinx_fontawesome; extra == "dev"
+Requires-Dist: sphinx-autoapi; extra == "dev"
+
+OMMX adaptor for Python-MIP
+============================
+![PyPI - Version](https://img.shields.io/pypi/v/ommx-python-mip-adapter)
+
+This package provides an adaptor for the [Python-MIP](https://www.python-mip.com/) from/to [OMMX](https://github.com/Jij-Inc/ommx)
+
+Python-MIP as a solver in OMMX toolchain
+-----------------------------------------
+```mermaid
+sequenceDiagram
+    participant O as Other OMMX toolchain
+    participant A as Adapter
+    participant P as Python-MIP
+    O->>A: ommx::Instance and Parameters for Python-MIP;
+    A->>P: Translate into Python-MIP input
+    P->>P: Solve with CBC, Gurobi, or other solvers
+    P->>A: Solution
+    A->>O: ommx:Solution
+```
+
+Python-MIP as a user interface to create OMMX instance
+-------------------------------------------------------
+TBW
+
+Usage
+======
+`ommx-python-mip-adapter` can be installed from PyPI as follows:
+
+```bash
+pip install ommx-python-mip-adapter
+```
+
+Python-MIP can be used through `ommx-python-mip-adapter` by using the following:
+
+```python markdown-code-runner
+import ommx_python_mip_adapter as adapter
+from ommx.v1.decision_variables_pb2 import DecisionVariable, Bound
+from ommx.v1.instance_pb2 import Instance
+from ommx.v1.function_pb2 import Function
+from ommx.v1.linear_pb2 import Linear
+from ommx.v1.solution_pb2 import SolutionList
+
+ommx_instance = Instance(
+    decision_variables=[
+        DecisionVariable(
+            id=1,
+            kind=DecisionVariable.KIND_INTEGER,
+            bound=Bound(lower=0, upper=5),
+        ),
+    ],
+    objective=Function(
+        linear=Linear(
+            terms=[Linear.Term(id=1, coefficient=1)]
+        ),
+    ),
+)
+ommx_instance_bytes = ommx_instance.SerializeToString()
+
+# Convert from `ommx.v1.Instance` to `mip.Model`
+model = adapter.instance_to_model(ommx_instance_bytes)
+model.optimize()
+# Create `ommx.v1.SolutionList` from Optimized `mip.Model`
+ommx_solutions_bytes = adapter.model_to_solution(
+    model, ommx_instance_bytes
+)
+
+print(SolutionList.FromString(ommx_solutions_bytes))
+```
+
+Reference
+==============
+- [OMMX-Python-MIP-Adapter API Reference](https://jij-inc.github.io/ommx-python-mip-adapter/index.html)

{ommx_python_mip_adapter-0.0.2 → ommx_python_mip_adapter-0.1.0}/ommx_python_mip_adapter.egg-info/SOURCES.txt

@@ -3,15 +3,21 @@ LICENSE-APACHE
 LICENSE-MIT
 README.md
 pyproject.toml
+.github/workflows/docs.yml
 .github/workflows/publish.yml
 .github/workflows/test_and_lint.yml
+docs/source/conf.py
+docs/source/index.rst
 ommx_python_mip_adapter/__init__.py
 ommx_python_mip_adapter/_version.py
-ommx_python_mip_adapter/ommx_to_python_mip.py
+ommx_python_mip_adapter/adapter.py
+ommx_python_mip_adapter/exception.py
 ommx_python_mip_adapter.egg-info/PKG-INFO
 ommx_python_mip_adapter.egg-info/SOURCES.txt
 ommx_python_mip_adapter.egg-info/dependency_links.txt
 ommx_python_mip_adapter.egg-info/requires.txt
 ommx_python_mip_adapter.egg-info/top_level.txt
 tests/conftest.py
-tests/test_omm_to_python_mip.py
+tests/test_adapter.py
+tests/test_import.py
+tests/test_integration.py

ommx_python_mip_adapter-0.1.0/ommx_python_mip_adapter.egg-info/requires.txt

@@ -0,0 +1,13 @@
+ommx<0.2.0,>=0.1.1
+mip
+
+[dev]
+markdown-code-runner
+mypy
+numpy
+pyright
+pytest
+sphinx
+sphinx_rtd_theme
+sphinx_fontawesome
+sphinx-autoapi

{ommx_python_mip_adapter-0.0.2 → ommx_python_mip_adapter-0.1.0}/pyproject.toml

@@ -18,15 +18,22 @@ classifiers = [
     "License :: OSI Approved :: MIT License",
 ]
 dependencies = [
-    "ommx >= 0.1.0",
+    "ommx >= 0.1.1, < 0.2.0",
+    "mip",
 ]
 
 
 [project.optional-dependencies]
 dev = [
-    "pytest",
+    "markdown-code-runner",
     "mypy",
+    "numpy",
     "pyright",
+    "pytest",
+    "sphinx",
+    "sphinx_rtd_theme",
+    "sphinx_fontawesome",
+    "sphinx-autoapi",
 ]
 
 

ommx_python_mip_adapter-0.1.0/tests/test_adapter.py

@@ -0,0 +1,147 @@
+import mip
+import pytest
+
+from ommx.v1.constraint_pb2 import Constraint
+from ommx.v1.decision_variables_pb2 import DecisionVariable
+from ommx.v1.function_pb2 import Function
+from ommx.v1.instance_pb2 import Instance
+from ommx.v1.linear_pb2 import Linear
+from ommx.v1.quadratic_pb2 import Quadratic
+from ommx.testing import SingleFeasibleLPGenerator, DataType
+
+import ommx_python_mip_adapter as adapter
+
+from ommx_python_mip_adapter.exception import OMMXPythonMIPAdapterError
+
+def test_error_invalid_instance():
+    with pytest.raises(OMMXPythonMIPAdapterError) as e:
+        adapter.instance_to_model(b"invalid")
+    assert "Invalid `ommx_instance_bytes`" in str(e.value)
+
+
+def test_error_not_suppoerted_decision_variable():
+    ommx_instance = Instance(
+        decision_variables=[
+            DecisionVariable(
+                id=1,
+                kind=DecisionVariable.KIND_UNSPECIFIED,
+            )
+        ],
+    )
+    ommx_instance_bytes = ommx_instance.SerializeToString()
+
+    with pytest.raises(OMMXPythonMIPAdapterError) as e:
+        adapter.instance_to_model(ommx_instance_bytes)
+    assert "Not supported decision variable" in str(e.value)
+
+
+def test_error_nonlinear_objective():
+    # Objective function: 2.3 * x * x
+    ommx_instance = Instance(
+        decision_variables=[
+            DecisionVariable(
+                id=0,
+                kind=DecisionVariable.KIND_CONTINUOUS,
+            ),
+        ],
+        objective=Function(
+            quadratic=Quadratic(
+                rows=[1],
+                columns=[1],
+                values=[2.3],
+            ),
+        ),
+    )
+    ommx_instance_bytes = ommx_instance.SerializeToString()
+
+    with pytest.raises(OMMXPythonMIPAdapterError) as e:
+        adapter.instance_to_model(ommx_instance_bytes)
+    assert "The objective function must be" in str(e.value)
+    
+
+def test_error_nonlinear_constraint():
+    # Objective function: 0
+    # Constraint: 2.3 * x * x = 0
+    ommx_instance = Instance(
+        decision_variables=[
+            DecisionVariable(
+                id=1,
+                kind=DecisionVariable.KIND_CONTINUOUS,
+            ),
+        ],
+        objective=Function(
+            constant=0,
+        ),
+        constraints=[
+            Constraint(
+                function=Function(
+                    quadratic=Quadratic(
+                        rows=[1],
+                        columns=[1],
+                        values=[2.3],
+                    ),
+                ),
+                equality=Constraint.EQUALITY_EQUAL_TO_ZERO,
+            ),
+        ],
+    )
+    ommx_instance_bytes = ommx_instance.SerializeToString()
+
+    with pytest.raises(OMMXPythonMIPAdapterError) as e:
+        adapter.instance_to_model(ommx_instance_bytes)
+    assert "Only linear constraints are supported" in str(e.value)
+
+
+def test_error_not_supported_constraint_equality():
+    # Objective function: 0
+    # Constraint: 2x ?? 0 (equality: unspecified)
+    ommx_instance = Instance(
+        decision_variables=[
+            DecisionVariable(
+                id=1,
+                kind=DecisionVariable.KIND_CONTINUOUS,
+            ),
+        ],
+        objective=Function(
+            constant=0,
+        ),
+        constraints=[
+            Constraint(
+                function=Function(
+                    linear=Linear(
+                        terms=[
+                            Linear.Term(
+                                id=1,
+                                coefficient=2,
+                            ),
+                        ],
+                    ),
+                ),
+                equality=Constraint.EQUALITY_UNSPECIFIED,
+            ),
+        ],
+    )
+    ommx_instance_bytes = ommx_instance.SerializeToString()
+
+    with pytest.raises(OMMXPythonMIPAdapterError) as e:
+        adapter.instance_to_model(ommx_instance_bytes)
+    assert "Not supported constraint equality" in str(e.value)
+
+
+def test_error_not_optimized_model():
+    model = mip.Model()
+
+    with pytest.raises(OMMXPythonMIPAdapterError) as e:
+        adapter.model_to_solution(model, b"")
+    assert "`model.status` must be " in str(e.value)
+
+
+def test_error_invalid_ommx_instance_bytes():
+    generator = SingleFeasibleLPGenerator(10, DataType.INT)
+    ommx_instance_bytes = generator.get_v1_instance()
+    model = adapter.instance_to_model(ommx_instance_bytes)
+    model.optimize()
+
+    with pytest.raises(OMMXPythonMIPAdapterError) as e:
+        adapter.model_to_solution(model, b"invalid")
+    assert "Invalid `ommx_instance_bytes`" in str(e.value)

ommx_python_mip_adapter-0.1.0/tests/test_import.py

@@ -0,0 +1,9 @@
+def test_import():
+    import ommx_python_mip_adapter as adapter
+    from ommx_python_mip_adapter import instance_to_model
+    from ommx_python_mip_adapter import model_to_solution
+
+    assert adapter.instance_to_model
+    assert adapter.model_to_solution
+    assert instance_to_model
+    assert model_to_solution

ommx_python_mip_adapter-0.1.0/tests/test_integration.py

@@ -0,0 +1,142 @@
+import pytest
+
+from ommx.v1.constraint_pb2 import Constraint
+from ommx.v1.decision_variables_pb2 import DecisionVariable, Bound
+from ommx.v1.function_pb2 import Function
+from ommx.v1.instance_pb2 import Instance
+from ommx.v1.linear_pb2 import Linear
+from ommx.v1.solution_pb2 import SolutionList
+from ommx.testing import SingleFeasibleLPGenerator, DataType
+
+import ommx_python_mip_adapter as adapter
+
+
+@pytest.mark.parametrize(
+    "generater",
+    [
+        SingleFeasibleLPGenerator(10, DataType.INT),
+        SingleFeasibleLPGenerator(10, DataType.FLOAT),
+    ]
+)
+def test_integration_lp(generater):
+    # Objective function: 0
+    # Constraints:
+    #     A @ x = b    (A: regular matrix, b: constant vector)
+    ommx_instance_bytes = generater.get_v1_instance()
+
+    model = adapter.instance_to_model(ommx_instance_bytes)
+    model.optimize()
+    ommx_solution = adapter.model_to_solution(model, ommx_instance_bytes)
+
+    ommx_solution_obj = SolutionList.FromString(ommx_solution)
+    expected_solution_obj = SolutionList.FromString(
+        generater.get_v1_solution()
+    )
+
+    # Check the number of solutions
+    assert len(ommx_solution_obj.solutions) == 1
+
+    actual_entries = ommx_solution_obj.solutions[0].entries 
+    expected_entries = expected_solution_obj.solutions[0].entries
+
+    # Check the solution of each decision variable
+    for key, actual_value in actual_entries.items():
+        expected_value = expected_entries[key]
+        assert actual_value == pytest.approx(expected_value)
+
+
+def test_integration_milp():
+    # Objective function: - x1 - x2
+    # Constraints:
+    #     3x1 - x2 - 6 <= 0
+    #     -x1 + 3x2 - 6 <= 0
+    #     0 <= x1 <= 10    (x: integer)
+    #     0 <= x2 <= 10    (x: continuous)
+    # Optimal solution: x1 = 3, x2 = 3
+    LOWER_BOUND = 0
+    UPPER_BOUND = 10
+    ommx_instance = Instance(
+        decision_variables=[
+            DecisionVariable(
+                id=1,
+                kind=DecisionVariable.KIND_INTEGER,
+                bound=Bound(
+                    lower=LOWER_BOUND,
+                    upper=UPPER_BOUND,
+                ),
+            ),
+            DecisionVariable(
+                id=2,
+                kind=DecisionVariable.KIND_CONTINUOUS,
+                bound=Bound(
+                    lower=LOWER_BOUND,
+                    upper=UPPER_BOUND,
+                ),
+            ),
+        ],
+        objective=Function(
+            linear=Linear(
+                terms=[
+                    Linear.Term(
+                        id=1,
+                        coefficient=-1,
+                    ),
+                    Linear.Term(
+                        id=2,
+                        coefficient=-1,
+                    ),
+                ],
+            )
+        ),
+        constraints=[
+            Constraint(
+                function=Function(
+                    linear=Linear(
+                        terms=[
+                            Linear.Term(
+                                id=1,
+                                coefficient=3,
+                            ),
+                            Linear.Term(
+                                id=2,
+                                coefficient=-1,
+                            ),
+                        ],
+                        constant=-6
+                    ),
+                ),
+                equality=Constraint.EQUALITY_LESS_THAN_OR_EQUAL_TO_ZERO,
+            ),
+            Constraint(
+                function=Function(
+                    linear=Linear(
+                        terms=[
+                            Linear.Term(
+                                id=1,
+                                coefficient=-1,
+                            ),
+                            Linear.Term(
+                                id=2,
+                                coefficient=3,
+                            ),
+                        ],
+                        constant=-6
+                    ),
+                ),
+                equality=Constraint.EQUALITY_LESS_THAN_OR_EQUAL_TO_ZERO,
+            ),
+        ],
+    )
+    ommx_instance_bytes = ommx_instance.SerializeToString()
+
+    model = adapter.instance_to_model(ommx_instance_bytes)
+    model.optimize()
+    ommx_solution = adapter.model_to_solution(model, ommx_instance_bytes)
+
+    ommx_solution_obj = SolutionList.FromString(ommx_solution)
+
+    assert len(ommx_solution_obj.solutions) == 1
+
+    actual_entries = ommx_solution_obj.solutions[0].entries
+    assert actual_entries[1] == pytest.approx(3)
+    assert actual_entries[2] == pytest.approx(3)

ommx_python_mip_adapter-0.0.2/PKG-INFO

@@ -1,47 +0,0 @@
-Metadata-Version: 2.1
-Name: ommx_python_mip_adapter
-Version: 0.0.2
-Summary: An adapter for the Python-MIP from/to OMMX.
-Author-email: "Jij Inc." <info@j-ij.com>
-Project-URL: Repository, https://github.com/Jij-Inc/ommx-python-mip-adapter
-Project-URL: Issues, https://github.com/Jij-Inc/ommx-python-mip-adapter/issues
-Classifier: Programming Language :: Python :: 3 :: Only
-Classifier: Programming Language :: Python :: 3.8
-Classifier: Programming Language :: Python :: 3.9
-Classifier: Programming Language :: Python :: 3.10
-Classifier: Programming Language :: Python :: 3.11
-Classifier: Programming Language :: Python :: 3.12
-Classifier: License :: OSI Approved :: Apache Software License
-Classifier: License :: OSI Approved :: MIT License
-Requires-Python: >=3.8
-Description-Content-Type: text/markdown
-License-File: LICENSE-APACHE
-License-File: LICENSE-MIT
-Requires-Dist: ommx>=0.1.0
-Provides-Extra: dev
-Requires-Dist: pytest; extra == "dev"
-Requires-Dist: mypy; extra == "dev"
-Requires-Dist: pyright; extra == "dev"
-
-OMMX adaptor for Python-MIP
-============================
-
-This package provides an adaptor for the [Python-MIP](https://www.python-mip.com/) from/to [OMMX](https://github.com/Jij-Inc/ommx)
-
-Python-MIP as a solver in OMMX toolchain
------------------------------------------
-```mermaid
-sequenceDiagram
-    participant O as Other OMMX toolchain
-    participant A as Adapter
-    participant P as Python-MIP
-    O->>A: ommx::Instance and Parameters for Python-MIP;
-    A->>P: Translate into Python-MIP input
-    P->>P: Solve with CBC, Gurobi, or other solvers
-    P->>A: Solution
-    A->>O: ommx:Solution
-```
-
-Python-MIP as a user interface to create OMMX instance
--------------------------------------------------------
-TBW

ommx_python_mip_adapter-0.0.2/README.md

@@ -1,22 +0,0 @@
-OMMX adaptor for Python-MIP
-============================
-
-This package provides an adaptor for the [Python-MIP](https://www.python-mip.com/) from/to [OMMX](https://github.com/Jij-Inc/ommx)
-
-Python-MIP as a solver in OMMX toolchain
------------------------------------------
-```mermaid
-sequenceDiagram
-    participant O as Other OMMX toolchain
-    participant A as Adapter
-    participant P as Python-MIP
-    O->>A: ommx::Instance and Parameters for Python-MIP;
-    A->>P: Translate into Python-MIP input
-    P->>P: Solve with CBC, Gurobi, or other solvers
-    P->>A: Solution
-    A->>O: ommx:Solution
-```
-
-Python-MIP as a user interface to create OMMX instance
--------------------------------------------------------
-TBW

ommx_python_mip_adapter-0.0.2/ommx_python_mip_adapter/ommx_to_python_mip.py

@@ -1,2 +0,0 @@
-def ommx_to_python_mip() -> None:
-    print("Hello, OMMX-PythonMIP-Adapter!")

ommx_python_mip_adapter-0.0.2/ommx_python_mip_adapter.egg-info/PKG-INFO

@@ -1,47 +0,0 @@
-Metadata-Version: 2.1
-Name: ommx_python_mip_adapter
-Version: 0.0.2
-Summary: An adapter for the Python-MIP from/to OMMX.
-Author-email: "Jij Inc." <info@j-ij.com>
-Project-URL: Repository, https://github.com/Jij-Inc/ommx-python-mip-adapter
-Project-URL: Issues, https://github.com/Jij-Inc/ommx-python-mip-adapter/issues
-Classifier: Programming Language :: Python :: 3 :: Only
-Classifier: Programming Language :: Python :: 3.8
-Classifier: Programming Language :: Python :: 3.9
-Classifier: Programming Language :: Python :: 3.10
-Classifier: Programming Language :: Python :: 3.11
-Classifier: Programming Language :: Python :: 3.12
-Classifier: License :: OSI Approved :: Apache Software License
-Classifier: License :: OSI Approved :: MIT License
-Requires-Python: >=3.8
-Description-Content-Type: text/markdown
-License-File: LICENSE-APACHE
-License-File: LICENSE-MIT
-Requires-Dist: ommx>=0.1.0
-Provides-Extra: dev
-Requires-Dist: pytest; extra == "dev"
-Requires-Dist: mypy; extra == "dev"
-Requires-Dist: pyright; extra == "dev"
-
-OMMX adaptor for Python-MIP
-============================
-
-This package provides an adaptor for the [Python-MIP](https://www.python-mip.com/) from/to [OMMX](https://github.com/Jij-Inc/ommx)
-
-Python-MIP as a solver in OMMX toolchain
------------------------------------------
-```mermaid
-sequenceDiagram
-    participant O as Other OMMX toolchain
-    participant A as Adapter
-    participant P as Python-MIP
-    O->>A: ommx::Instance and Parameters for Python-MIP;
-    A->>P: Translate into Python-MIP input
-    P->>P: Solve with CBC, Gurobi, or other solvers
-    P->>A: Solution
-    A->>O: ommx:Solution
-```
-
-Python-MIP as a user interface to create OMMX instance
--------------------------------------------------------
-TBW

ommx_python_mip_adapter-0.0.2/ommx_python_mip_adapter.egg-info/requires.txt

@@ -1,6 +0,0 @@
-ommx>=0.1.0
-
-[dev]
-pytest
-mypy
-pyright

ommx_python_mip_adapter-0.0.2/tests/test_omm_to_python_mip.py

@@ -1,2 +0,0 @@
-def test_import():
-    import ommx_python_mip_adapter