Use markdown file instead of ipynb for introduction

Jij-Inc · Feb 6, 2025 · 4dbd466 · 4dbd466
1 parent ffaf98e
commit 4dbd466
Show file tree

Hide file tree

Showing 3 changed files with 60 additions and 105 deletions.
diff --git a/docs/ja/introduction.ipynb b/docs/ja/introduction.ipynb
diff --git a/docs/ja/introduction.md b/docs/ja/introduction.md
@@ -0,0 +1,55 @@
+# OMMXとは？
+
+OMMX（Open Mathematical prograMming eXchange; オミキス）とは、実務で数理最適化を応用する過程で必要となる、ソフトウェア間や人間同士のデータ交換を実現するためのオープンなデータ形式と、それを操作するためのSDKの総称です。
+
+数理最適化のワークフローは、通常、複数のメンバーやチームによって遂行されます。例えば、最適化問題を解くためにプログラムを実装する役割とデータ分析に基づく戦略を立案する役割とで作業分担するなど、各プロセスに専門のメンバーやチームが割り当てられます。それに伴い、複数の作業者の間でデータ交換が頻繁に発生します。
+
+さらに、ワークフローの各段階では、数理最適化ソフトウェアだけでなく、一般的なデータ分析ツールなど多様なソフトウェアが使用されるため、異なるソフトウェア間でも頻繁なデータ交換が発生します。
+
+また、データ交換に伴い、データに付随するメタ情報の管理も必要になります。例えば、データの作成日時、作成者、使用したソフトウェアのバージョン、適用したアルゴリズムの詳細、入力パラメータの設定値などです。これらの情報を適切に管理することは、試行錯誤や反復的なモデル修正が必要となる数理最適化のプロセスにおいて、分析や結果の再現性を確保するために不可欠です。
+
+```{figure} ./assets/introduction_01.png
+:alt: 数理最適化のワークフロー概略図
+
+数理最適化のワークフロー。
+```
+
+このように、数理最適化のワークフローを実践する際には、その過程で生じるデータの交換と管理が極めて重要です。OMMXは、このような課題に対応するために設計されました。OMMXによって、人間同士やソフトウェア間でのシームレスなデータ交換を可能にし、ワークフローの効率化と精度向上を実現します。
+
+## OMMXを構成する要素
+
+OMMXは次の4つのコンポーネントで構成されています：
+
+- OMMX Message
+
+    ソフトウェア間でデータを交換するためのデータ形式
+
+- OMMX Artifact
+
+    人間同士でデータを交換するためのパッケージ形式
+
+- OMMX SDK
+
+    OMMX MessageとOMMX Artifactを操作するための多言語ソフトウェア開発環境
+
+- OMMX Adapter
+
+    数理最適化ソフトウェアとOMMXとを相互に連携するためのソフトウェア
+
+
+OMMXは、複数の数理最適化ソフトウェア間で統一的なデータ交換を実現するために、OMMX Adapterを提供します。OMMX Adapterは、既存の数理最適化ソフトウェアとOMMXを連携させ、その入出力形式をOMMX Messageに準拠させます。これにより、OMMXユーザーはOMMX SDKを使ってOMMX Messageを作成するだけで、複数のソフトウェア間で統一的にデータを利用できるようになります。
+
+```{figure} ./assets/introduction_02.png
+:alt: OMMX MessageとOMMX Adapterの関係を表す図
+:width: 70%
+
+OMMXが実現するソフトウェア間のデータ交換。
+```
+
+また、人間同士のデータ交換を実現するため、OMMXはOMMX Artifactを提供します。OMMX Artifactは、OMMX Messageと関連メタデータを含む、OCI Artifact準拠のコンテナベースパッケージ形式です。これにより、OMMXユーザーはOMMX SDKを用いてOMMX Artifactを作成し、一般的なコンテナ基盤を活用してデータの管理・共有を効率的に行うことができます。
+
+```{figure} ./assets/introduction_03.png
+:alt: OMMX MessageとOMMX Artifactの関係を表す図
+
+OMMXが実現する人間同士のデータ交換。
+```
diff --git a/docs/ja/ommx_message/architecture.ipynb b/docs/ja/ommx_message/architecture.ipynb
@@ -5,41 +5,13 @@
    "metadata": {},
    "source": [
     "OMMX Message Design\n",
-    "=============\n",
+    "====================\n",
     "\n",
-    "[![doc](https://img.shields.io/badge/Protocol-Documentation-blue)](https://jij-inc.github.io/ommx/protobuf.html)\n",
+    "OMMX Messageはソフトウェア間でのデータの交換を行うためのデータ形式です。\n",
     "\n",
-    "## Why OMMX Message based on Protocol Buffers? Why not [JSON](https://www.json.org/json-en.html), [CBOR](https://cbor.io/), or [HDF5](https://www.hdfgroup.org/solutions/hdf5/)?\n",
-    "\n",
-    ":zap: We need to define a data schema for messages exchanged between applications, services, and databases that make up OROps.\n",
-    "\n",
-    "We have to discuss the following points to answer the question.\n",
-    "\n",
-    "- Where OMMX is used?\n",
-    "- Why schema is required?\n",
-    "- Text-based or Binary-based?\n",
-    "- Why Protocol Buffers?\n",
-    "\n",
-    "Note that this is a **better** selection, not the **best** selection. We have to keep considering these points and change the selection if necessary.\n",
-    "\n",
-    "### Where OMMX is used?\n",
-    "\n",
-    "Mathematical programming has been a subject of study in academic fields for a considerable period of time, and numerous software tools have been developed to improve the solving capability. However, these tools are basically designed for use in a research process. When we attempt to use these invaluable tools in a real-world business process, we refer to it as \"OROps\" (OR = operations research), like \"MLOps\" in machine-learning field, we have to face many problems. The most significant problem is the lack of interoperability between tools. We have to convert data between tools, and it is a time-consuming and error-prone process. OMMX is designed to solve this problem.\n",
-    "\n",
-    "### Why schema is required?\n",
-    "Different from research process where few researchers use and create few tools, in OROps, many developers use and create many tools. The interoperability between tools becomes significant issue due to this point. It is possible for human to manage input and output data stored in general purpose data format like JSON or HDF5 for few tools, but it is hard for many tools. Thus, we have to introduce machine-readable schema.\n",
-    "\n",
-    "### Text-based or Binary-based?\n",
-    "TBW\n",
-    "\n",
-    "### Why Protocol Buffers?\n",
-    "TBW\n",
-    "\n",
-    "## Compatibility\n",
-    "\n",
-    "- OMMX defines a protocol buffers schema with version like `v1`, `v2`, etc. `v1` schema has a namesapce `ommx.v1`.\n",
-    "- Schemas in `ommx.v1` will be compatible after [ommx.v1 schema release](https://github.com/Jij-Inc/ommx/milestone/3). Note that the schema can be changed incompatible way until this release.\n",
-    "- `v2` schema with namespace `ommx.v2` will start developing if we need to change the schema in incompatible way after `ommx.v1` release. Compatible changes will be made in `v1` schema also after its release. We never create namespaces like `ommx.v1_1`."
+    "スキーマの必要性\n",
+    "-------------\n",
+    "\n"
    ]
   }
  ],