docs/tutorial/ja/physics/IntroductionCoreInterface.ipynb
{
"cells": [
{
"cell_type": "markdown",
"metadata": {},
"source": [
"# OpenJij core interface入門"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"この章ではOpenJijのcore interface (core python interface)の使い方を説明します。\n",
"\n",
"core interfaceは前回までのチュートリアルよりも下部のレイヤーのAPIです。対象読者としては前回までのOpenJijチュートリアルを一通り終えて、イジングモデルやモンテカルロ法などの用語を知っている方を想定しています。具体的には\n",
"\n",
"* 最適化問題だけでなくサンプリングや研究用途など、より専門的な用途にOpenJijを用いたい\n",
"* アニーリングスケジュールの設定や、使用するアルゴリズム等を直接触りたい\n",
"\n",
"といった目的に利用できます。"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"## OpenJij core interface について\n",
"\n",
"前回までのチュートリアルを通して、OpenJijを用いた様々な問題の解き方やベンチマークの取り方などを紹介してきました。\n",
"OpenJijは最下層の部分は統計物理学の数値計算手法である、マルコフ連鎖モンテカルロ法(MCMC)をベースにC++を用いて実装されています。\n",
"今まで触れてきたPythonモジュールはこのC++インターフェースを直接ラップしたpythonライブラリである**openjij.cxxjij**を呼び出す形となっています。図にすると次のような包含関係があります。\n",
"\n",
"{width=80%}\n",
"\n",
"OpenJij core interfaceを用いることでOpenJij上の全ての機能を使用することができます。よって最適化問題のみならず、**統計物理学の数値計算ツール**として研究用途で使用することもできます。また、C++インターフェースを用いることで、より高速な演算を行うことができます。\n",
"\n",
"本チュートリアルではより使いやすいPythonインターフェースのopenjij.cxxjijを紹介します。\n",
"インストールにはpipを使用します。"
]
},
{
"cell_type": "code",
"execution_count": 1,
"metadata": {},
"outputs": [
{
"name": "stdout",
"output_type": "stream",
"text": [
"Requirement already satisfied: openjij in /opt/conda/lib/python3.9/site-packages (0.5.33)\n",
"Requirement already satisfied: dimod<0.12.0 in /opt/conda/lib/python3.9/site-packages (from openjij) (0.10.17)\n",
"Requirement already satisfied: requests<2.29.0,>=2.28.0 in /opt/conda/lib/python3.9/site-packages (from openjij) (2.28.1)\n",
"Requirement already satisfied: scipy<1.10.0,>=1.7.3 in /opt/conda/lib/python3.9/site-packages (from openjij) (1.8.1)\n",
"Requirement already satisfied: jij-cimod<1.5.0,>=1.4.6 in /opt/conda/lib/python3.9/site-packages (from openjij) (1.4.36)\n",
"Requirement already satisfied: numpy<1.24.0,>=1.17.3 in /opt/conda/lib/python3.9/site-packages (from openjij) (1.23.2)\n",
"Requirement already satisfied: pyparsing<3.0.0,>=2.4.7 in /opt/conda/lib/python3.9/site-packages (from dimod<0.12.0->openjij) (2.4.7)\n",
"Requirement already satisfied: idna<4,>=2.5 in /opt/conda/lib/python3.9/site-packages (from requests<2.29.0,>=2.28.0->openjij) (3.3)\n",
"Requirement already satisfied: urllib3<1.27,>=1.21.1 in /opt/conda/lib/python3.9/site-packages (from requests<2.29.0,>=2.28.0->openjij) (1.26.12)\n",
"Requirement already satisfied: certifi>=2017.4.17 in /opt/conda/lib/python3.9/site-packages (from requests<2.29.0,>=2.28.0->openjij) (2022.6.15)\n",
"Requirement already satisfied: charset-normalizer<3,>=2 in /opt/conda/lib/python3.9/site-packages (from requests<2.29.0,>=2.28.0->openjij) (2.1.1)\n",
"Name: openjij\n",
"Version: 0.5.33\n",
"Summary: Framework for the Ising model and QUBO.\n",
"Home-page: https://www.openjij.org\n",
"Author: Jij Inc.\n",
"Author-email: info@openjij.org\n",
"License: Apache License 2.0\n",
"Location: /opt/conda/lib/python3.9/site-packages\n",
"Requires: dimod, jij-cimod, numpy, requests, scipy\n",
"Required-by: jijbench, jijmodeling, jijzept\n"
]
}
],
"source": [
"!pip install openjij\n",
"!pip show openjij"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"## OpenJij core interfaceの概要\n",
"\n",
"まずは、OpenJij core interfaceの使い方を見るために、\n",
"変数のサイズが$N=5$の古典スピン ($\\sigma = \\pm 1$)イジング問題をSimulated Annealingで解いてみましょう。\n",
"ハミルトニアンは以下のようになります。\n",
"\\begin{align*}\n",
"H &= \\sum_{i<j}J_{ij}\\sigma_i \\sigma_j + \\sum_{i=1}^{N}h_i \\sigma_i \\\\\n",
"\\sigma_i &= \\pm 1 (i=1 \\cdots N)\n",
"\\end{align*}\n",
"\n",
"縦磁場と相互作用が\n",
"\n",
"\\begin{align*}\n",
"h_i = -1 \\ \\mathrm{for\\ } \\forall i,\\ J_{ij} = -1 \\ \\mathrm{for\\ } \\forall i,\\ j\n",
"\\end{align*}\n",
"\n",
"の場合、各スピンは1の値をとった方がエネルギーが低くなるため、$\\{\\sigma_i\\} = \\{1,1,1,1,1\\}$が最適解となります。この問題を解いてみましょう。\n",
"Pythonコードを用いた一通りの流れは次のようになります。\n",
"\n",
"> core interfaceはイジング問題に特化したソルバです。このためQUBOとの変換は実装されていません。QUBOとの変換を行うには今までのチュートリアルを参照し、core interfaceを呼ぶ前にQUBOからイジング問題へ変換してください。"
]
},
{
"cell_type": "code",
"execution_count": 5,
"metadata": {},
"outputs": [
{
"name": "stdout",
"output_type": "stream",
"text": [
"The solution is [1, 1, 1, 1, 1].\n"
]
}
],
"source": [
"# core interfaceではopenjijの代わりにcxxjijをインポートします。\n",
"import openjij.cxxjij as cj\n",
"\n",
"# まず相互作用行列を作成してあげます。Graphモジュールを使います。\n",
"import openjij.cxxjij.graph as G\n",
"\n",
"# 問題サイズN=5の密結合グラフ(Dense)を定義します。\n",
"N = 5\n",
"J = G.Dense(N)\n",
"# 相互作用を設定してあげます。\n",
"for i in range(N):\n",
" for j in range(N):\n",
" #J[i,i]以外に-1を入力\n",
" J[i,j] = 0 if i == j else -1.0\n",
"\n",
"# 縦磁場を設定してあげます。\n",
"for i in range(N):\n",
" # J[i,i] = -1でも同じ結果となります。\n",
" J[i] = -1\n",
"\n",
"# 続いてGraphから計算を行うためのSystemを作成します。\n",
"import openjij.cxxjij.system as S\n",
"\n",
"# 今回は通常の古典モンテカルロ計算のシステムを使用します。\n",
"system = S.make_classical_ising(J.gen_spin(), J)\n",
"# アニーリングスケジュールを設定します。Utilityモジュールを使用します。\n",
"import openjij.cxxjij.utility as U\n",
"schedule = U.make_classical_schedule_list(0.1, 100, 10, 10)\n",
"\n",
"# 実際にアニーリングを走らせます。Algorithmモジュールを使用します。\n",
"# モンテカルロステップの更新方法として単純なSingleSpinFlipを用います。\n",
"import openjij.cxxjij.algorithm as A\n",
"A.Algorithm_SingleSpinFlip_run(system, schedule)\n",
"\n",
"# 結果を取得しまAす。Resultモジュールにあるget_solutionを用います。\n",
"import openjij.cxxjij.result as R\n",
"print(\"The solution is {}.\".format(R.get_solution(system)))"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"出てきた答えが$[1,1,1,1,1]$であることが確認できます。低レイヤーのAPIのため設定する項目は多いですが、その分詳細な設定が可能となります。\n",
"\n",
"### モジュール一覧\n",
"\n",
"コード例に出てきたように、OpenJij core interfaceでは主に`graph`, `system`, `algorithm`などのモジュールから構成されています。それぞれのモジュールを組み合わせることで様々な種類、アルゴリズムでイジングモデルを計算することが可能となります。また新たにアルゴリズムを実装する際に拡張が容易であるという特徴を備えています。次章以降で詳細な説明を行います。\n",
"\n",
"#### Graph\n",
"\n",
"イジングハミルトニアンの係数$J_{ij}$を保持するためのモジュールです。基本的に密結合 (全てのJijが0以外の値を持つモデルに適している)を扱う`Dense`と疎結合 (Jijの多くの値が0であるモデルに適している)`Sparse`などがあります。\n",
"\n",
"#### System\n",
"\n",
"`system`では、モンテカルロ等の計算における現在のシステムの状態を保持するためのデータ構造が定義されています。具体的には\n",
"\n",
"- 古典イジングモデル (スピン配列)\n",
"- 横磁場イジングモデル (トロッター分解も含んだスピン配列)\n",
"- GPU実装古典、量子イジングモデル\n",
"\n",
"等が定義されています。モンテカルロ法を始めとする計算手法には様々な手法があります(もしくは今後新しい手法が開発されていくことでしょう)。そのため、OpenJijでは各々の計算手法に対応するデータ構造とアルゴリズム、そして計算結果の取得インターフェースを分離することにより、様々なアルゴリズムを追加することが容易に行えるように設計されています。\n",
"\n",
"#### Updater\n",
"\n",
"どのような手法で`system`を更新していくかを定義します。具体的には\n",
"\n",
"- SingleSpinFlip Update\n",
"- SwendsenWang Update\n",
"\n",
"などの手法が実装されています。Systemの種類によって使用できるUpdaterは決まっています。\n",
"具体的に、どのようなUpdaterがどのSystemで使えるかは、これ以降のチュートリアルで具体的に見ていきます。\n",
"\n",
"> core python interfaceでは`algorithm`に統合されています。\n",
"\n",
"#### Algorithm\n",
"\n",
"`updater`を用いてどのようなスケジュールでアニーリングアルゴリズムを実行するかなど、アルゴリズムを実行する役割を担います。\n",
"`Algorithm_[Updaterの種類]_run`で、対応したUpdaterを用いて実行することができます。\n",
"\n",
"#### Result\n",
"\n",
"`system`からスピン配位などの情報を得るために使用されます。\n",
"\n",
"### コーディングフロー\n",
"\n",
"コーディングの流れは基本的には以下に示すようなものとなります。問題の規模が大きくなってもこの流れは変わりません。\n",
"\n",
"- `graph`モジュールで$J_{ij}, h_{i}$を定義\n",
"- `graph`モジュールを元に`system`の作成\n",
"- `system`に対応する`updater`を選択し、`Algorithm_[Updaterの種類]_run`でアルゴリズムの実行\n",
"- `result.get_solution(system)`でシステムのスピン配位を取得、もしくは`system`から直に取得"
]
}
],
"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.9.12"
}
},
"nbformat": 4,
"nbformat_minor": 4
}