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

定数項

num_unit_steps

integer

1

100

10

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

timeout

integer

0

600000 2

10000

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

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:全て出力)

1(1,2,3)

polynomial, matrix, constraints いずれかの入力が必須。constraintspolynomial または matrix と組み合わせることが可能

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} + 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 を二次元配列の要素とします

注釈

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

注釈

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

matrix

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

QUBO多項式の行列表現

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

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

注釈

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

注釈

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

制約条件式の右辺 (数値)

3(1,2)

リクエストパラメータにおける polynomial と同様の形式

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\) が設定されます。

num_unit_steps

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

timeout

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

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_unit_steps

integer

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

timeout

number

指定されたタイムアウト値

num_iterations

integer

タイムアウトまでの探索回数

penalty_calibration

bool

ペナルティ係数の自動調整機能が有効化されたか

penalty_multipliers

array

解の探索に用いられたペナルティ係数の配列

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)を要素に持つ) を格納した配列を返します。

feasibilities

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

execution_parameters

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

num_unit_steps

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

timeout

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

num_iterations

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

penalty_calibration

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

  • リクエストパラメータ penalty_calibration = true

  • constraints パラメータが与えられる

  • polynomial または matrix にて 0 以外の値が与えられる

penalty_multipliers

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

エラー時レスポンス

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":{"num_unit_steps":10,"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":{"num_unit_steps":10,"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":{"num_unit_steps":10,"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]]}