API Reference

URL

https://optigan.fixstars.com

認証

リクエストヘッダに 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行列 ([number, number, ...] を配列要素とする二次元配列)
constraints		array	○ [1]				制約条件オブジェクトの配列
constant		number				0	定数項
timeout		integer		0	600000 [2]	10000	タイムアウト時間(ミリ秒)
num_gpus		integer		0	4 [2]	1	計算に使用する GPU の数
penalty_calibration		boolean				true	制約条件オブジェクトのペナルティ関数の係数を自動調整するか
outputs		object					出力制御パラメータ
	spins	boolean				true	スピン配列を出力するか
	energies	boolean				true	エネルギー値を出力するか
	feasibilities	boolean				true	解の実行可能性を出力するか
	sort	boolean				true	スピン配列とエネルギーをエネルギー値で昇順にソートするか
	duplicate	boolean				false	エネルギー値の重複した解を出力するか
	num_outputs	integer				1	スピン配列とエネルギー値の出力数 (0:全て出力)

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} + c\]

に対し、係数 \(Q_{i,j}\) と定数 \(c\) を二次元配列の要素として次のように与えます。

二次の項 \(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,j}\) → 配列 \(\left[i, i, Q_{i,i} \right]\) または \(\left[i, Q_{i,i} \right]\) (\(i \ge 0\))

例: 二次の項 \(x_0\) の係数として \(Q_{0,0}=1.0\) を指定する場合、要素数3の配列 [0, 0, 1.0] または要素数2の配列 [0, 1.0] を二次元配列の要素とします
定数項 \(c\) → 配列 \(\left[c \right]\) または数値 \(c\)

例: 定数項 \(c=0.5\) を指定する場合、要素数1の配列 [0.5] または数値 0.5 を二次元配列の要素とします

注釈

polynomial と matrix の両方を指定することは出来ません。

注釈

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

matrix

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

QUBO多項式の行列表現

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

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

注釈

polynomial と matrix の両方を指定することは出来ません。

注釈

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}\]

と解釈されます。つまり \(x_i x_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多項式について、\(i\) 番目 (\(i=0, 1, \cdots, N-1\)) の行に対応した配列の長さは \(N-i\) である必要があります。

下三角行列

行列要素 \(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多項式について、\(i\) 番目 (\(i=0, 1, \cdots, N-1\)) の行に対応した配列の長さは \(i\) である必要があります。

constraints

QUBO多項式における変数間に課せられる制約条件オブジェクトを配列で与えます。

注釈

polynomial または matrix と組み合わせることも可能です

制約条件オブジェクトの定義は次の通りです。

key	sub key	type	req.	default	description
penalty		array	○		ペナルティ関数 (二次多項式) [3]
multiplier		number		1	ペナルティ関数の係数
condition		object			制約条件式
	left	array		`penalty`	制約条件式の左辺 (二次多項式) [3]
	op	string		=	制約条件式の左辺と右辺を結ぶ演算子
	right	number		0	制約条件式の右辺 (数値)

penalty は制約条件式に対応する二次多項式で表されたペナルティ関数です。ペナルティ関数には係数を multiplier として与えることが出来ます。ペナルティ関数に係数をかけた式が最適化対象として polynomial または matrix に加えられます。係数の自動調整機能が有効の場合、multiplier は係数の初期値として扱われます。

制約条件として満たすべき式は condition オブジェクトで与えられます。省略した場合は penalty = 0 が制約条件式と解釈されます。省略しない場合、制約条件式の左辺 (二次多項式) は left で指定します。制約条件式の右辺 (数値) は right で指定します。省略した場合は \(0\) です。

左辺と右辺を結ぶ演算子は文字列で op に指定します。省略した場合は = すなわち left = right と解釈されます。演算子として指定できる文字列は下記の通りです。

等式 left = right
- op: =, ==, eq, EQ
不等式 left < right
- op: <, lt, LT
不等式 left <= right
- op: <=, le, LE
不等式 left > right
- op: >, gt, GT
不等式 left >= right
- op: >=, ge, GE

constant

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

timeout

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

num_gpus

使用する GPU の数を与えます。省略した場合 \(1\) が設定されます。利用可能な GPU 数の最大値は契約プランに依存し、0は利用可能な最大数を意味します。

penalty_calibration

制約条件におけるペナルティ関数の自動調整機能を有効にするかを指定します。省略した場合は有効 (true) です。

outputs

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

spins

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

energies

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

feasibilities

アニーリング結果においてそれぞれの解の実行可能性を表す配列を出力するかを指定します。

sort

アニーリング結果 (スピン配列、エネルギー、実行可能性) を制約条件の充足数とエネルギー値でソートします。true の場合は昇順、false の場合は降順です。昇順の場合のソートの優先順位は下記の通りです。

制約条件の充足数の多い順
制約条件の充足数が同一の場合はエネルギー値の小さい順

duplicate

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

num_outputs

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

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

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

正常実行時レスポンス

key	sub key	type	description
execution_time		object	実行時間(ms)
	annealing_time	number	アニーリング実行時間
	queue_time	number	キュー待ち時間
	cpu_time	number	CPU処理時間
	time_stamps	array	解が得られた時刻
energies		array	エネルギー値
spins		array	スピン配列
feasibilities		array	解が実行可能かどうかを表す bool 配列
execution_parameters		object
	num_gpus	integer	計算に使用された GPU 数
	timeout	number	指定されたタイムアウト値
	num_iterations	integer	タイムアウトまでの探索回数
	penalty_calibration	bool	ペナルティ係数の自動調整機能が有効化されたか
	penalty_multipliers	array	解の探索に用いられたペナルティ係数の配列
	version	string	Amplify AE の実行時バージョン情報
message		string	警告メッセージ

execution_time

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

annealing_time

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

time_stamps

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

queue_time

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

cpu_time

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

energies

アニーリング結果のエネルギー値 (number) を格納した配列を返します。この値はペナルティ関数の値を含まないことに注意してください。

spins

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

feasibilities

アニーリング結果のそれぞれの解が実行可能解がどうか (与えられた全ての制約条件を満たすか) を格納した bool 配列を返します。

execution_parameters

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

num_gpus

計算に使用された GPU 数を返します。

timeout

指定されたアニーリングの実行時間を返します。単位はミリ秒(ms)です。

num_iterations

タイムアウトまでに実行された探索内部の反復回数を返します。返却値は必ず1以上です。反復回数が少なすぎる場合、問題規模に対してタイムアウト値が小さい可能性があります。

penalty_calibration

制約条件オブジェクトにおけるペナルティ関数の係数の自動調整機能が有効化されたかを返します。下記の条件に一致した場合に true となります。

リクエストパラメータ penalty_calibration = true
constraints パラメータが与えられる
polynomial または matrix にて 0 以外の値が与えられる

penalty_multipliers

解の探索に用いられた、制約条件オブジェクトにおけるペナルティ関数の係数を配列で返します。ペナルティ係数の自動調整機能が実行時に有効な場合、調整の最終値が格納されます。

version

Amplify AE の実行時バージョン情報を {バージョン番号}-{実行ハードウェアID} という書式で返します。

message

実行時に警告が発生した場合、このフィールドに格納されます。

エラー時レスポンス

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]]}' https://optigan.fixstars.com/solve
{"execution_parameters":{"timeout":50.0,"num_iterations":1,"penalty_calibration":false,"penalty_multipliers":[]},"execution_time":{"annealing_time":33.24964799999999,"queue_time":0.494037000000022,"cpu_time":150.34307499999995,"time_stamps":[32.959393]},"feasibilities":[true],"energies":[-1.0],"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' https://optigan.fixstars.com/solve -s -X POST --data-binary @-
  {"execution_parameters":{"timeout":50.0,"num_iterations":1,"penalty_calibration":false,"penalty_multipliers":[]},"execution_time":{"annealing_time":33.764886999999998,"queue_time":0.4529419999999839,"cpu_time":150.00948299999997,"time_stamps":[33.429204]},"feasibilities":[true],"energies":[-1.0],"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' https://optigan.fixstars.com/solve -s -X POST --data-binary @- | zcat
  {"execution_parameters":{"timeout":50.0,"num_iterations":1,"penalty_calibration":false,"penalty_multipliers":[]},"execution_time":{"annealing_time":33.763845999999997,"queue_time":0.5169769999999939,"cpu_time":149.07931299999999,"time_stamps":[33.443633]},"feasibilities":[true],"energies":[-1.0],"spins":[[1,1]]}