Update OpenJij Quickstart to use OMMX Adapter (#42)

Author: Zengor

docs/en/introduction.ipynb

@@ -17,7 +17,7 @@
     "\n",
     "`jijmodeling` is a tool for describing mathematical models using Python code, not for evaluating or solving mathematical models. This specification focuses on the algebraic structure of mathematical models, independent of instance data, allowing for logical consideration, verification, and faster modification of mathematical models. It also functions as a schema for generating the input format expected by solvers.\n",
     "\n",
-    "To solve the mathematical models described with `jijmodeling` using a solver, you need to combine them with actual instance data and convert them into the input format for a specific solver using other tools such as the [JijZept service](https://www.jijzept.com) or the freely available [jijmodeling-transpiler](https://www.documentation.jijzept.com/docs/jijmodelingtranspiler/)."
+    "To solve the mathematical models described with `jijmodeling` using a solver, you need to combine them with actual instance data and convert them into the input format for a specific solver using other tools such as the [JijZept service](https://www.jijzept.com)."
    ]
   },
   {
@@ -43,7 +43,7 @@
     {
      "data": {
       "text/plain": [
-       "'1.10.0'"
+       "'1.12.4'"
       ]
      },
      "execution_count": 1,
@@ -68,7 +68,7 @@
  ],
  "metadata": {
   "kernelspec": {
-   "display_name": ".venv",
+   "display_name": "Python 3 (ipykernel)",
    "language": "python",
    "name": "python3"
   },
@@ -82,9 +82,9 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.11.4"
+   "version": "3.9.18"
   }
  },
  "nbformat": 4,
- "nbformat_minor": 2
+ "nbformat_minor": 4
 }

docs/en/quickstart/openjij.ipynb

@@ -8,10 +8,10 @@
     "\n",
     "Let's look at a basic example to understand how to use `jijmodeling`. Below, we will explain the steps to create a simple mathematical model, transform it, and run it with a solver. The first two sections are sufficient with just `jijmodeling`, but we recommend using [Jupyter Notebook](https://jupyter.org) to easily check LaTeX output.\n",
     "\n",
-    "In the third section, we will use [JijModelingTranspiler](https://www.documentation.jijzept.com/docs/jijmodelingtranspiler/) and [OpenJij](https://openjij.github.io/OpenJij/index.html). JijModelingTranspiler and OpenJij can be installed using `pip`.\n",
+    "In the third section, we will use [`ommx-openjij-adapter`](https://pypi.org/project/ommx-openjij-adapter/) to solve our model through [OpenJij](https://openjij.github.io/OpenJij/index.html). `ommx-openjij-adapter` can be installed through `pip`:\n",
     "\n",
     "```bash\n",
-    "pip install jijmodeling-transpiler openjij\n",
+    "pip install ommx-openjij-adapter\n",
     "```"
    ]
   },
@@ -60,7 +60,7 @@
        "$$\\begin{array}{cccc}\\text{Problem:} & \\text{my problem} & & \\\\& & \\min \\quad \\displaystyle n \\cdot \\left(a + b + c\\right) & \\\\\\text{{s.t.}} & & & \\\\ & \\text{c1} & \\displaystyle 2 \\cdot \\left(b + c\\right) \\leq 75 &  \\\\ & \\text{c2} & \\displaystyle a + b \\leq 40 &  \\\\\\text{{where}} & & & \\\\& a & 0\\text{-dim integer variable}\\\\ & & \\text{lower bound: }5 & \\\\ & & \\text{upper bound: }20 & \\\\& b & 0\\text{-dim integer variable}\\\\ & & \\text{lower bound: }1 & \\\\ & & \\text{upper bound: }20 & \\\\& c & 0\\text{-dim integer variable}\\\\ & & \\text{lower bound: }20 & \\\\ & & \\text{upper bound: }30 & \\\\\\end{array}$$"
       ],
       "text/plain": [
-       "<jijmodeling.Problem at 0x145e1b300>"
+       "<jijmodeling.Problem at 0x5badb53ce740>"
       ]
      },
      "execution_count": 2,
@@ -139,7 +139,7 @@
        "$$\\begin{array}{cccc}\\text{Problem:} & \\text{knapsack} & & \\\\& & \\max \\quad \\displaystyle \\sum_{i = 0}^{N - 1} v_{i} \\cdot x_{i} & \\\\\\text{{s.t.}} & & & \\\\ & \\text{weight limit} & \\displaystyle \\sum_{i = 0}^{N - 1} w_{i} \\cdot x_{i} \\leq W &  \\\\\\text{{where}} & & & \\\\& x & 1\\text{-dim binary variable}\\\\\\end{array}$$"
       ],
       "text/plain": [
-       "<jijmodeling.Problem at 0x157139210>"
+       "<jijmodeling.Problem at 0x5badb53e17f0>"
       ]
      },
      "execution_count": 4,
@@ -172,7 +172,7 @@
        "$$\\begin{array}{cccc}\\text{Problem:} & \\text{knapsack} & & \\\\& & \\max \\quad \\displaystyle \\sum_{i = 0}^{N - 1} v_{i} \\cdot x_{i} & \\\\\\text{{s.t.}} & & & \\\\ & \\text{weight limit} & \\displaystyle \\sum_{i = 0}^{N - 1} w_{i} \\cdot x_{i} \\leq W &  \\\\\\text{{where}} & & & \\\\& x & 1\\text{-dim binary variable}\\\\\\end{array}$$"
       ],
       "text/plain": [
-       "<jijmodeling.Problem at 0x145e24520>"
+       "<jijmodeling.Problem at 0x5badb53ffc20>"
       ]
      },
      "execution_count": 5,
@@ -206,11 +206,12 @@
    "source": [
     "## Solving the Model\n",
     "\n",
-    "With the above code, we were able to build a model, but `jijmodeling` alone doesn't do much besides LaTeX output. You need to combine it with instance data to generate input for the solver. As an example, let's see how to transform the mathematical model built with `jijmodeling` into a QUBO using the freely available [JijModelingTranspiler](https://www.documentation.jijzept.com/docs/jijmodelingtranspiler/) and solve the model using [OpenJij](https://openjij.github.io/OpenJij/index.html). Note that tools provided by [JijZept](https://www.documentation.jijzept.com/docs/jijzept/) also accept mathematical models built with `jijmodeling` as input.\n",
+    "With the above code, we were able to build a model, but that model alone doesn't do much besides LaTeX output. You need to combine it with instance data to generate input for the solver. First, we define the instance data to be input into the `Placeholder`s in our model, and register that data in the `Interpreter` object.\n",
     "\n",
-    "This section aims to provide a simple demonstration, so we won't explain JijModelingTranspiler or OpenJij in detail. Please refer to their respective documentation for more information.\n",
+    "You can register instance data by passing a dictionary with the following keys and values to the constructor of the `Interpreter` class:\n",
     "\n",
-    "Below, we use JijModelingTranspiler to transform the mathematical model built with `jijmodeling` and instance data into a QUBO."
+    "- Key: String set in the `name` property of the `Placeholder` object\n",
+    "- Value: Data to be input"
    ]
   },
   {
@@ -219,66 +220,80 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "from jijmodeling_transpiler.core import compile_model\n",
-    "from jijmodeling_transpiler.core.pubo import transpile_to_pubo\n",
-    "\n",
-    "data = {\n",
-    " \"W\": 100,\n",
-    " \"v\": [100, 90, 80, 70, 60, 50, 40, 30],\n",
-    " \"w\": [1, 5, 10, 20, 30, 40, 50, 60, 70]\n",
+    "instance_data = {\n",
+    " \"W\": 100,                                  # Data of the knapsack's weight capacity\n",
+    " \"v\": [100, 90, 80, 70, 60, 50, 40, 30],    # Data of item values\n",
+    " \"w\": [1, 5, 10, 20, 30, 40, 50, 60, 70]    # Data of item weights\n",
     "}\n",
-    "\n",
-    "compiled = compile_model(problem, data)\n",
-    "qubo, _ = transpile_to_pubo(compiled).get_qubo_dict()"
+    "interpreter = jm.Interpreter(instance_data)"
    ]
   },
   {
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "Now we have obtained a QUBO that can be accepted as input by OpenJij. Writing out QUBOs manually is prone to errors, but using `jijmodeling` and `jijmodeling_transpiler` eliminates such errors and makes verification easier. Let's actually input the QUBO into `openjij` and solve the problem."
+    "To convert the mathematical model to an instance, use the `Interpreter.eval_problem` method. By passing the `Problem` object to the `eval_problem` method of the `Interpreter` object with registered instance data, the `Placeholder`s in the `Problem` object will be filled with the instance data and converted to an OMMX instance:"
    ]
   },
   {
    "cell_type": "code",
    "execution_count": 7,
    "metadata": {},
+   "outputs": [],
+   "source": [
+    "instance = interpreter.eval_problem(problem)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    ":::{hint}\n",
+    "The return value of `Interpreter.eval_problem` is an `ommx.v1.Instance` object. For more details about OMMX, please refer to [here](https://github.com/Jij-Inc/ommx).\n",
+    ":::"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Now we have an OMMX instance which we can use as input to the OpenJij sampler. Let’s use `ommx-openjij-adapter` to actually sample the problem:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 17,
+   "metadata": {},
    "outputs": [
     {
-     "data": {
-      "text/plain": [
-       "Sample(sample={0: 1, 1: 1, 2: 1, 3: 1, 4: 1, 5: 1, 6: 0, 7: 0}, energy=-5.501111111111113, num_occurrences=1)"
-      ]
-     },
-     "execution_count": 7,
-     "metadata": {},
-     "output_type": "execute_result"
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "Optimal value of the objective function: 369.234375\n"
+     ]
     }
    ],
    "source": [
-    "import openjij as oj\n",
+    "from ommx_openjij_adapter import OMMXOpenJijSAAdapter\n",
     "\n",
-    "sampler = oj.SASampler()\n",
-    "response = sampler.sample_qubo(qubo, num_reads=1)\n",
-    "response.first"
+    "# Solve through SCIP and retrieve results as an ommx.v1.Solution\n",
+    "samples = OMMXOpenJijSAAdapter.sample(instance, num_reads=1)\n",
+    "\n",
+    "print(f\"Optimal value of the objective function: {samples.best_feasible().objective}\")"
    ]
   },
   {
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "The above code uses simulated annealing from `openjij`, and `num_reads=1` indicates sampling only once. By increasing the value of `num_reads`, you can sample multiple times and explore various results using the response object. However, for this problem, all samples reach the optimal solution, so we will sample once and look at the \"best\" solution found.\n",
-    "\n",
-    "```\n",
-    "Sample(sample={0: 1, 1: 1, 2: 1, 3: 1, 4: 1, 5: 1, 6: 0, 7: 0}, energy=-5.501111111111113, num_occurrences=1)\n",
-    "```"
+    "The above code uses simulated annealing from `openjij`, and `num_reads=1` indicates sampling only once. By increasing the value of `num_reads`, you can sample multiple times and explore various results using the response object. However, for this problem, all samples reach the optimal solution, so we sample once and look at the \"best\" solution found."
    ]
   },
   {
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "The above response object shows the values found by `openjij` for each decision variable. You can do much more to better process and visualize the results using JijModelingTranspiler and OpenJij, or reuse the same mathematical model for different purposes, but please refer to their respective documentation pages for more information."
+    "The above samples object shows the values found by `openjij` for each decision variable. You can do much more to better process and visualize the results using the OMMX Adapter and OpenJij, or reuse the same mathematical model for different purposes, but please refer to their respective documentation pages for more information."
    ]
   },
   {
@@ -289,13 +304,13 @@
     "\n",
     "- [Examples](https://www.documentation.jijzept.com/docs/category/learn)\n",
     "- [JijZept](https://www.documentation.jijzept.com/docs/jijzept/)\n",
-    "- [JijModelingTranspiler](https://www.documentation.jijzept.com/docs/jijmodelingtranspiler/)"
+    "- [OMMX](https://jij-inc.github.io/ommx/en/introduction.html)"
    ]
   }
  ],
  "metadata": {
   "kernelspec": {
-   "display_name": ".venv",
+   "display_name": "Python 3 (ipykernel)",
    "language": "python",
    "name": "python3"
   },
@@ -309,9 +324,9 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.11.4"
+   "version": "3.9.18"
   }
  },
  "nbformat": 4,
- "nbformat_minor": 2
+ "nbformat_minor": 4
 }

docs/en/quickstart/scip.ipynb

@@ -140,7 +140,7 @@
    "source": [
     "## Step2. Register Instance Data in the `Interpreter` Object\n",
     "\n",
-    "Prepare the instance data to be input into the `Placeholder` of the mathematical model formulated in Step1, and register it in the `Interpreter` object.\n",
+    "Prepare the instance data to be input into the `Placeholder`s of the mathematical model formulated in Step1, and register it in the `Interpreter` object.\n",
     "\n",
     "You can register instance data by passing a dictionary with the following keys and values to the constructor of the `Interpreter` class:\n",
     "\n",
@@ -349,7 +349,7 @@
    "metadata": {},
    "source": [
     ":::{hint}\n",
-    "`ommx_pyscipopt_adapter` の `model_to_solution` の返却値は `ommx.v1.Solution` オブジェクトです。OMMXについて詳しく知りたい場合は[こちら](https://github.com/Jij-Inc/ommx)を参照してください。\n",
+    "`OMMXPySCIPOptAdapter.solve` returns an `ommx.v1.Solution` object. For more information on OMMX, see [here](https://github.com/Jij-Inc/ommx).\n",
     ":::"
    ]
   }

docs/en/references/tips.ipynb

@@ -5,6 +5,8 @@
    "id": "4bb9ca8e-e701-4e76-863a-c39115b5b33e",
    "metadata": {},
    "source": [
+    "# Tips\n",
+    "\n",
     "## Defining `Element` Along a Set\n",
     "\n",
     "Some users may want to create an index $i \\in \\{0, 1, 2\\}$ using Python's set `Set` as follows:\n",
@@ -504,7 +506,7 @@
    "id": "4c3a952a-d1c4-47b7-98df-0d843c9bf6a7",
    "metadata": {},
    "source": [
-    "It is recommended to construct instance data for use with `jijmodeling_transpiler` or JijZept as follows."
+    "It is recommended to construct instance data for use with `jm.Interpreter` or JijZept as follows."
    ]
   },
   {
@@ -533,7 +535,7 @@
  ],
  "metadata": {
   "kernelspec": {
-   "display_name": ".venv",
+   "display_name": "Python 3 (ipykernel)",
    "language": "python",
    "name": "python3"
   },
@@ -547,7 +549,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.9.16"
+   "version": "3.9.18"
   }
  },
  "nbformat": 4,