Add OMMX adapter guide (#267)

Add guidelines to the docs on how to structure OMMX-Solver adapters.
This includes a skeleton for an abstract base class to be included in a
future release of ommx, to be used as a baseline interface adapters
should share.

doc/_toc.yml

@@ -24,6 +24,7 @@ parts:
   - caption: "OMMX Ecosystem"
     chapters:
       - file: ommx_ecosystem/links
+      - file: ommx_ecosystem/adapter
   - caption: "API Reference"
     chapters:
       - url: https://jij-inc.github.io/ommx/protobuf.html

doc/ommx_ecosystem/adapter.ipynb

@@ -0,0 +1,121 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "id": "b578922f-02f2-4169-b16b-d3b5db062d40",
+   "metadata": {},
+   "source": [
+    "# OMMX Adapter実装ガイド\n",
+    "\n",
+    "本ドキュメントは、OMMXからSolverを実行するためのAdapterを実装する際の推奨事項を記載したものである。下記の内容に従いOMMX Adapterを実装することで、他のOMMX Adapterと一定程度の一貫性を保つことができ、複数のOMMX Adapterを利用するユーザーにとってよりよいユーザー体験の提供に繋がる。そのため、OMMXコミュニティとしては以下の内容に従うことを推奨したい。\n",
+    "\n",
+    "## 推奨事項\n",
+    "\n",
+    "- OMMXからSolverを利用するためのアダプター `OMMXxxxAdapter`は、抽象基底クラス `SolverAdapter`を継承して実装することを推奨する\n",
+    "    ```python\n",
+    "    from ommx.ommx_adapter import SolverAdapter\n",
+    "\n",
+    "    class OMMXxxxAdapter(SolverAdapter):\n",
+    "        ...\n",
+    "    ``` \n",
+    "- `SolverAdapter`に実装されているメソッドの引数以外のものを引数として定義する場合は、キーワード限定引数を利用し、デフォルト値を設定するものとする\n",
+    "    ```python\n",
+    "    class OMMXxxxAdapter(SolverAdapter):\n",
+    "        ...\n",
+    "        def __init__(self, ommx_instance: ommx.v1.Instance, *, kwarg=\"default\", ...):\n",
+    "            ...\n",
+    "    ```\n",
+    "- `OMMXxxxAdapter.solve` メソッドは、OMMXからSolverを簡単に使うための静的メソッドとして提供されるべきである\n",
+    "    - Solverのパラメーターを全て引数として実装する必要はない。そのようなユースケースは `OMMXxxxAdapter` クラスを直接使うことで実現できれば十分である\n",
+    "    ```python\n",
+    "    class OMMXxxxAdapter(SolverAdapter):\n",
+    "        ...\n",
+    "        @staticmethod\n",
+    "        def solve(ommx_instance: ommx.v1.Instance) -> ommx.v1.Solution:\n",
+    "            ...\n",
+    "    ```\n",
+    "- `OMMXxxxAdapter` のコンストラクタ内で、以下の処理を行うようにすることを推奨する\n",
+    "    - `ommx.v1.Instance` からSolverの入力形式（データやオブジェクト）を生成する処理\n",
+    "    - `OMMXxxxAdapter.decode` に必要となるデータの生成する処理\n",
+    "- `OMMXxxxAdapter.solver_input` プロパティは、OMMXからSolverの入力形式（データやオブジェクト）を取得するプロパティとして提供されるべきである\n",
+    "    ```python\n",
+    "    class OMMXxxxAdapter(SolverAdapter):\n",
+    "        ...\n",
+    "        @property\n",
+    "        def solver_input(self) -> SolverInput:\n",
+    "            ...\n",
+    "    ```\n",
+    "- `OMMXxxxAdapter.decode` メソッドは、Solverの出力形式（データやオブジェクト）を `ommx.v1.Instance` へと変換するメソッドとして提供されるべきである\n",
+    "\n",
+    "## 検討事項\n",
+    "\n",
+    "以下では、推奨するほどではないが実装を検討すると良いものを列挙する。\n",
+    "\n",
+    "- `OMMXxxxAdapter.decode_to_state` メソッド: Solverの出力形式（データやオブジェクト）を `ommx.v1.State` に変換するためのメソッド\n",
+    "    \n",
+    "    ```python\n",
+    "    from ommx.ommx_adapter import SolverAdapter\n",
+    "    \n",
+    "    class OMMXxxxAdapter(SolverAdapter):\n",
+    "    \t...\n",
+    "    \tdef decode_to_state(self, data: SolverOutput) -> ommx.v1.State:\n",
+    "    \t\t...\n",
+    "    ```\n",
+    "    \n",
+    "- `yyy_to_instance` 関数: Solverの入力形式を `ommx.v1.Instance` に変換する関数\n",
+    "    \n",
+    "    ```python\n",
+    "    def xxx_to_instance(data: Any) -> ommmx.v1.Instance:\n",
+    "    \t\t...\n",
+    "    ```\n",
+    "    \n",
+    "\n",
+    "## 推奨事項を満たすOMMX Adapterが保証するユーザー体験\n",
+    "\n",
+    "上記の推奨事項を満たすOMMX Adapterは、以下の一貫したユーザー体験を与えることができる。\n",
+    "\n",
+    "- Solverを気軽に利用したいユーザー（Solverの入出力方法やパラメーターを把握したくないユーザー）は、共通で提供されている静的メソッド `solve` で簡単にSolverを実行できる\n",
+    "    \n",
+    "    ```python\n",
+    "    from ommx_xxx_adapter import OMMXxxxAdapter\n",
+    "    \n",
+    "    ommx_solution = OMMXxxxAdapter.solve(ommx_instance)\n",
+    "    ```\n",
+    "    \n",
+    "- Solverをチューニングして利用したいユーザーは、直接 `OMMXxxxAdapter` クラスを使うことでSolverのパラメーター等を設定して実行できる\n",
+    "\n",
+    "    ```python\n",
+    "    from ommx_xxx_adapter import OMMXxxxAdapter\n",
+    "\n",
+    "    adapter = OMMXxxxAdapter(ommx_instance)\n",
+    "    solver_input = adapter.solver_input\n",
+    "    \n",
+    "    ... # この部分でSolverのチューニングを行ってから実行し、solver_outputを得る\n",
+    "    \n",
+    "    ommx_solution = adapter.decode(solver_output)\n",
+    "    ```"
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "Python 3 (ipykernel)",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 3
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython3",
+   "version": "3.12.2"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}