APIリファレンス

Web API v1

Annealing Cloud Web APIではイジングモデルを使ったアニーリングマシンの操作をHTTPで通信を行うWebAPIとして提供します。

基本的な使い方

エンドポイント
 https://annealing−cloud.com/api/v1/ 
認証方式

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

 Authorization: Bearer XXXXXXXXXXXXXXXXXXXXX 
パラメータ形式

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

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

$ curl -H 'Authorization: Bearer XXXXXXXXXXXXXXXXXXXXX ' -d '{"model": [ [0,0,0,0,1], [0,1,0,0,-1] ]}' https://annealing-cloud.com/api/v1/solve
APIステータス

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

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

POST /solve

リクエストパラメータ(JSON形式)
key 説明 必須 データ型 最小値 最大値 デフォルト値
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
50.0 10.0
 temperature_target 最終温度 - number 0以上
※1
50.0 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
設定値について
model

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

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

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

modelの係数

係数pは-3〜3の範囲内で設定してください。0が設定された場合は、未設定として扱われます。

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

modelの座標

座標は以下の範囲内で設定してください。

0 <= x <= 96
0 <= y <= 96

parameters

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

outputs

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

※1 parameters.temperature_initial/temperature_targetの最小値

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

※2 outputs.num_outputsの最大値

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

設定例
{
  "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 実行結果 - -
 status 実行ステータス integer 0
 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"
}