API Reference

認証

リクエストヘッダに Authorization を追加し、Bearer スキームとトークンを値に設定します。:

Authorization: Bearer <TOKEN>

リクエストパラメータ

エンドポイント : /solve メソッド : POST

key

sub key

type

req.

min

max

default

description

polynomial

array

1

QUBO多項式 ([integer, integer, number] を配列要素とする二次元配列)

matrix

array

1

QUBO行列 ([double, double, …] を配列要素とする二次元配列)

constant

number

0

定数項

num_unit_steps

integer

1

0

アニーリングの単位ステップ数

timeout

integer

0

600000 2

10000

タイムアウト時間(ミリ秒)

outputs

object

出力制御パラメータ

spins

boolean

true

スピン配列を出力するか

energies

boolean

true

エネルギー値を出力するか

sort

boolean

true

スピン配列とエネルギーをエネルギー値で昇順にソートするか

duplicate

boolean

false

エネルギー値の重複した解を出力するか

num_outputs

integer

1

スピン配列とエネルギー値の出力数 (0:全て出力)

1(1,2)

polynomialmatrix どちらかが必須

2

共有版のみ制約 (占有型では制約されない)

polynomial

QUBO多項式における各変数のインデックスと係数の組を二次元配列で与えます。QUBO多項式

\[H \left( \mathbf{x} \right) = \sum_{i < j}{Q_{i,j} x_i x_j} + \sum_{i}{Q_{i,i} x_i}\]

に対し、\(Q_{i,j}\) を配列 \(\left[i, j, Q_{i,j} \right]\) (\(i \ge 0, j\ge 0\)) として表します。例えば二次の項 \(x_1x_2\) の係数として \(Q_{1,2}=-4.0\) を指定する場合、要素数3の配列 [1, 2, -4.0] を配列要素として与えます。

一次の項 \(Q_{i,i}\) を与える場合には、最初の二つの要素に同じ整数値を指定します。例えば \(x_2\) の係数として \(Q_{2,2} = 0.5\) を指定する場合 [2, 2, 0.5] を配列要素とします。

Note

polynomialmatrix どちらか一方を必ず指定してください。

Note

QUBO多項式が全結合の場合 matrix を入力とした方が高速に動作する可能性があります。

matrix

QUBO多項式を row major の行列形式で与えます。値は二次元配列形式とします。

QUBO多項式の行列表現

\[H \left( \mathbf{x} \right) = \mathbf{x}^{ \mathrm{ T } } \mathbf{Q} \mathbf{x}\]

に対して下記3通りいずれかの方法で行列要素を入力します。

Note

polynomialmatrix 必ずどちらか一方を指定してください。

Note

QUBO多項式が1024bit以上で疎結合の場合 polynomial を入力とした方が高速に動作する可能性があります。

正方行列

行列要素 \(Q_{i,j}\) 対し、二次元配列の各行を \(\left[Q_{i,0}, Q_{i,1}, Q_{i,2} \cdots \right]\) として表します。

入力されたQUBO行列は多項式として、

\[H \left( \mathbf{x} \right) = \sum_{i < j}{\left(Q_{i,j} + Q_{j,i} \right) x_i x_j} + \sum_{i}{Q_{i,i} x_i}\]

と解釈されます。つまり \(q_i q_j \left(i \ne j \right)\) の係数には、QUBO行列の非対角要素の和 \(Q_{ij} + Q_{ji}\) が対応します。

二次元配列の配列数と各行の長さは一致する必要があります。

上三角行列

行列要素 \(Q_{i,j}\) 対し、二次元配列の各行を \(\left[Q_{i,i}, Q_{i,i+1}, Q_{i,i+2}, \cdots, \right]\) として表します。

入力されたQUBO行列は多項式として、

\[H \left( \mathbf{x} \right) = \sum_{i < j}{Q_{i,j} x_i x_j} + \sum_{i}{Q_{i,i} x_i}\]

と解釈されます。

二次元配列の各行の長さは列数から行番号を引いた数に一致する必要があります。つまり \(N\) 変数のQUBO多項式について、配列の長さは \(\left[N, N-1, \cdots, 1 \right]\) である必要があります。

下三角行列

行列要素 \(Q_{i,j}\) 対し、二次元配列の各行を \(\left[Q_{i,0}, Q_{i,1}, Q_{i,2}, \cdots, Q_{i,i} \right]\) として表します。

入力されたQUBO行列は多項式として、

\[H \left( \mathbf{x} \right) = \sum_{i > j}{Q_{i,j} x_i x_j} + \sum_{i}{Q_{i,i} x_i}\]

と解釈されます。

二次元配列の各行の長さは行番号に一致する必要があります。つまり \(N\) 変数のQUBO多項式について、配列の長さは \(\left[1, 2, \cdots, N \right]\) である必要があります。

constant

QUBO多項式の定数項を実数で指定します。省略した場合 \(0\) が設定されます。

num_unit_steps

アニーリングスケジュールの滑らかさを表す変数 (モンテカルロステップ) を \(1\) 以上の整数で指定します。省略した場合は自動に設定されます。 値を大きくすると解の品質が安定しますが、必要以上に大きくすると解の収束が遅くなります。

timeout

アニーリングの実行時間を与えます。省略した場合 \(10000\) (10秒) が設定されます。解は必ず1つ以上出力するように動作するため、指定時間以内に終了することは保証されません。

outputs

レスポンスに含める内容を設定できます。

spins

アニーリング結果においてスピン配列を出力するかを指定します。

energies

アニーリング結果においてエネルギー値を出力するかを指定します。

sort

アニーリング結果においてスピン配列とエネルギーをエネルギー値でソートします。true の場合は昇順、false の場合は降順です。

duplicate

エネルギー値が同値でも変数の組合せが異なる場合に別の解として出力します。

num_outputs

結果の出力数を指定します。

エネルギー値が更新されたタイミングで解が記録されます。その後 sort の指定に従いソートされ、最大数として num_outputs だけ先頭から解を結果に出力します。

duplicate = true の場合には、エネルギーが同値であっても別の組合せの解が見つかった場合に出力が行われます。そのため実際に出力される解の数と num_outputs が一致しないことがあるので注意してください。 num_outputs は重複のないエネルギー値の数に対応します。

正常実行時レスポンス

key

sub key

type

description

execution_time

object

実行時間(ms)

annealing_time

number

アニーリング実行時間

quere_time

number

キュー待ち時間

cpu_time

number

CPU処理時間

time_stamps

array

解が得られた時刻

energies

array

エネルギー値

spins

array

スピン配列

execution_parameters

object

num_unit_steps

integer

実行アニーリングステップ数

execution_time

アニーリング計算の実行時間の情報を返します。単位はミリ秒(ms)です。

annealing_time

アニーリング実行時間を返します。

time_stamps

アニーリング開始時刻を0として、それぞれの解が得られた時刻を格納した配列を返します。outputs.sortnum_outputs の指定に依らず、エネルギー値が更新 (duplicate = true の場合には同値を含む) された時刻が全て出力されます。

queue_time

キューの待ち時間を返します。

cpu_time

アニーリング前処理・後処理やGPUメモリの転送などCPU処理時間の合計を返します。

energies

アニーリング結果のエネルギー値 (number) を格納した配列を返します。

spins

アニーリング結果のスピン配列 (array: 0または1の値(integer)を要素に持つ) を格納した配列を返します。

execution_parameters

アニーリング実行時のパラメータの情報を返します。

num_unit_steps

実行時のアニーリングの単位ステップ数を返します。

エラー時レスポンス

key

sub key

type

description

error

string

エラーメッセージ

error

エラーメッセージを返します。

実行例

多項式形式で \(H = - q_0 q_1\) をリクエストします。タイムアウトは 50ms です。

$ curl -H 'Authorization: Bearer XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX' -H 'Content-Type: application/json; charset=UTF-8' -H 'X-Accept: application/json' -X POST -d '{"timeout": 50, "polynomial": [[0, 1, -1.0]]}' http://113.43.211.53/solve
{"execution_parameters":{"num_unit_steps":10},"execution_time":{"annealing_time":51.999267,"queue_time":0.030848,"cpu_time":8.798146,"time_stamps":[51.944010]},"energies":[-1.00000000],"spins":[[1,1]]}

リクエストデータを圧縮する場合は Content-Encoding ヘッダを追加してください。圧縮形式として gzip または deflate が有効です。

$ echo '{"timeout": 50, "polynomial": [[0, 1, -1.0]]}' | gzip | \
  curl -H 'Authorization: Bearer XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX' -H "Content-Encoding: gzip" -H 'X-Accept: application/json' http://113.43.211.53/solve -s -X POST --data-binary @-
{"execution_parameters":{"num_unit_steps":10},"execution_time":{"annealing_time":34.091691,"queue_time":0.133176,"cpu_time":295.596854,"time_stamps":[33.962967]},"energies":[-1.00000000],"spins":[[1,1]]}

レスポンスデータを圧縮する場合は Accept-Encoding ヘッダを追加してください。 圧縮形式として gzip または deflate が有効です。

$ echo '{"timeout": 50, "polynomial": [[0, 1, -1.0]]}' | gzip | \
  curl -H 'Authorization: Bearer XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX' -H 'Content-Encoding: gzip' -H 'Accept-Encoding: gzip' -H 'X-Accept: application/json' http://113.43.211.53/solve -s -X POST --data-binary @- | zcat
{"execution_parameters":{"num_unit_steps":10},"execution_time":{"annealing_time":34.091691,"queue_time":0.133176,"cpu_time":295.596854,"time_stamps":[33.962967]},"energies":[-1.00000000],"spins":[[1,1]]}