APIリファレンス

Web API v2

Annealing Cloud Web APIではイジングモデルを使ったアニーリングマシンの操作をHTTPで通信を行うWebAPIとして提供します。
Web API v2では、ASIC版(4bit)、GPU(King’s graph)版(32bit/int)、GPU(King’s graph)版(32bit/float)より選択して実行することができます。 各版の違いはCMOSアニーリングについてをご覧ください。

基本的な使い方

エンドポイント

 https://annealing−cloud.com/api/v2/ 

認証方式

リクエストヘッダにAuthorization: Bearerヘッダを追加し、トークンを設定してください。
APIトークンを取得するには、トークン発行リクエストを行ってください。トークンの有効期限は発行から30日間です。

 Authorization: Bearer XXXXXXXXXXXXXXXXXXXXX 

パラメータ形式

入力・出力ともにJSON形式となります。入力パラメータはHTTP bodyに指定のJSONフォーマットで設定してください。

リクエスト実行例(cURLの場合)

$ curl -H 'Authorization: Bearer XXXXXXXXXXXXXXXXXXXXX ' -d '{"type" : 5, "model": [ [0,0,0,0,1], [0,1,0,0,-1] ]}' https://annealing-cloud.com/api/v2/solve

APIステータス

通信の結果についてステータスコードを設定します。通信エラーなどシステムで判断不能なステータスを除き基本的にHTTPステータスは200とし、レスポンスJSONのstatusにて通知します。

code	status	reason
0	正常終了	-
3	認証エラー	トークン認証失敗(トークン期限切れ含む)
10	ビジー	サーバが処理待ち状態になっている
17	タイプ指定エラー	指定したタイプが存在しない
33	ハードウェアエラー
49	JSONフォーマット不正
50	パラメータ不正	不正なパラメータが含まれている
51	必須エラー	必須項目が未設定
52	モデル設定範囲エラー	許容範囲を超える座標が設定されている
53	モデル設定値エラー	許容範囲を超える値が設定されている
255	不明なエラー	不明なエラー

POST /solve

リクエストパラメータ(JSON形式)

key	説明	必須	データ型	最小値	最大値	デフォルト値
type	実行マシンタイプ	-	integer	-	-	-
num_executions	アニーリング実行回数	-	integer	1	10	1
model	イジングモデルを表す 2次元配列	◯	array	※次項に記載		-
parameters	実行パラメータ制御設定	-	object	-	-	-
temperature_num_steps	温度変化ステップ数	-	integer	1	100	10
temperature_step_length	温度ステップあたりの長さ	-	integer	1	1000	100
temperature_initial	初期温度	-	number	0以上 ※1	3.402823e+38	10.0
temperature_target	最終温度	-	number	0以上 ※1	3.402823e+38	0.01
outputs	レスポンスに含める値の制御	-	object	-	-	-
energies	エネルギー値を出力する	-	boolean	-	-	true
spins	スピン値配列を出力する	-	boolean	-	-	true
execution_time	実行時間を出力する(nsec)	-	boolean	-	-	false
num_outputs	スピン値とエネルギー値の出力数 (エネルギー値昇順, 0は全て出力)	-	integer	0	※2	0
averaged_spins	スピンのサイトあたりの 平均値を出力する	-	boolean	-	-	false
averaged_energy	エネルギーの平均値を 出力する	-	boolean	-	-	false

設定値について

type

処理を実行するマシンの種類を指定できます。以下より選択し、設定してください。

3 : GPU 32bit(int)
4 : GPU 32bit(float)
5 : ASIC 4bit

model

modelパラメータにはイジングモデルの頂点、または相互作用を表現する要素数5の整数値配列[x0, y0, x1, y1, p]を複数並べた形で設定します。指定の順番は計算結果に影響しません。

x, yはそれぞれイジングモデル上の座標(x軸、y軸)を表現したものになり、pは係数を表します。
イジングモデルの頂点=1次の項(磁場)を表す場合はx0 == x1, y0 == y1の形で設定し、2頂点の相互作用を表す場合はx0, y0とx1, y1が隣接するよう設定してください。

隣接の要件として上下左右および斜めを許容します。隣接しない2頂点の座標指定が含まれる場合、エラーとなります。

modelの座標、係数

座標xy、係数pはタイプ毎の指定可能な範囲内で設定してください。係数に0が設定された場合は、未設定として扱われます。

重複する座標または相互作用を設定した場合、pが加算されます。例えば[1, 1, 1, 2, 2]と[1, 1, 1, 2, -1]が同時に設定された場合、2 + (-1) = 1となり、[1, 1, 1, 2, 1]が指定されたものとして扱われます。なお、pは単項目としても合算値としても指定範囲内で設定してください。重複によって加算された結果、pが指定範囲外となる場合はエラーとなります。

座標、係数は以下の範囲内でそれぞれ設定してください。

type: 3

座標： 0 <= x <= 511, 0 <= y <= 511
係数： -2147483648 <= p <= 2147483647

type: 4

座標： 0 <= x <= 511, 0 <= y <= 511
係数： -3.402823e+38 <= p <= 3.402823e+38

type: 5

座標： 0 <= x <= 383, 0 <= y <= 383
係数： -7 <= p <= 7

parameters

アニーリングに用いる幾何冷却に基づく冷却スケジュールを定めるためのパラメータを設定できます。未設定の場合は初期値で動作します。詳細はこちらを参照してください。

outputs

返却結果に含める内容を設定できます。未設定の場合は初期値で動作します。

※1 parameters.temperature_initial/temperature_targetについて

・最小値
0以上の実数となります。0は含まない点にご注意ください。

※2 outputs.num_outputsの最大値

指定可能な最大値はそのリクエストのnum_executionsの回数となります。

設定例

{
  "num_executions": 5,
  "model": [
    [0,0,0,0,1],
    [0,1,0,2,-1],
    [1,0,1,1,1],
    [1,1,1,2,1],
    [2,0,2,1,1],
    [2,1,2,2,1],
    [0,0,1,0,1],
    [1,0,2,0,1],
    [0,1,1,1,-1]
  ],
  "parameters": {
    "temperature_initial": 30.0,
    "temperature_target": 0.0000001
  },
  "outputs": {
    "averaged_spins": true,
    "averaged_energy": true
  }
}

レスポンス(JSON形式)

key	説明	データ型	設定例
status	WebAPI実行結果	integer	0
message	メッセージ (エラー時のみ設定)	string	Invalid json format.
job_id	ジョブを特定するID	string	b26315de-a2b2-4766-b9fd-42ad34139512
result	実行結果	-	-
execution_time	実行時間 (nsec)	number	431290200
energies	エネルギー値 実行回数分の配列	array	[-3.0,-3.0,-2.0]
spins	スピン 実行回数分の3次元配列	array	[[[0,1,1],[1,0,-1],[1,2,1]],[[0,1,-1], ...
averaged_energy	エネルギーの平均値	number	-5.0
averaged_spins	スピンのサイトあたりの平均値	array	[[0,1,1],[1,0,-1],[1,2,1]]

設定例

{
  "status": 0,
  "result": {
    "energies": [-3.0,-3.0,-2.0],
    "execution_time":61881392,
    "spins":[[[1,0,1],[0,1,1],[1,2,1]],[[1,0,1],[0,1,1],[1,2,1]],[[1,0,1],[0,1,1],[1,2,1]]]
  },
  "job_id":"b26315de-a2b2-4766-b9fd-42ad34139512"
}