API Reference
URL
https://optigan.fixstars.com
Authentication
Add Authorization to the request header and set the Bearer scheme and token to the value.
Authorization: Bearer <TOKEN>
Request Parameters
End point : /solve
Method : POST
key 
sub key 
type 
req. 
min 
max 
default 
description 

polynomial 
array 
○ [1] 
QUBO polynomial (Twodimensional array with [integer, integer, number] as an array element) 

matrix 
array 
○ [1] 
QUBO matrix (Twodimensional array with [double, double, …] as an array element) 

constraints 
array 
○ [1] 
Array of constraint object 

constant 
number 
0 
Constant term 

timeout 
integer 
0 
600000 [2] 
10000 
Timeout period (milliseconds) 

num_gpus 
integer 
0 
4 [2] 
1 
Number of GPUs to use in the calculation 

penalty_calibration 
boolean 
true 
Whether to automatically calibrate the coefficients of the penalty functions of constraint objects 

outputs 
object 
Output control parameters 

spins 
boolean 
true 
Whether to output spin array 

energies 
boolean 
true 
Whether to output energy value 

feasibilities 
boolean 
true 
Whether to output feasibility of solutions 

sort 
boolean 
true 
Whether to sort spin array and energy in ascending order by energy value 

duplicate 
boolean 
false 
Whether to output solutions with the same energy values 

num_outputs 
integer 
1 
Number of outputs of spin arrays and energy values (0: output all) 
polynomial
A QUBO polynomial can be expressed as follows
where \(x_i\) are binary variables, \(Q_{i, j}\) the coefficients of the quadratic and linear terms, and \(c\) a constant term. Here, we express the above polynomial in terms of a twodimensional array whose element corresponds to each of the terms of the polynomial in the following way.
Quadratic term \(Q_{i,j}\) → Array \(\left[i, j, Q_{i,j} \right]\) (\(i \ge 0, j\ge 0\))
Example: For the quadratic term \(x_1x_2\) with the coefficient \(Q_{1,2}=4.0\), the corresponding element of the twodimensional polynomial array is specified by the 3element array
[1, 2, 4.0]
.Linear term \(Q_{i,j}\) → Array \(\left[i, i, Q_{i,i} \right]\) or \(\left[i, Q_{i,i} \right]\) (\(i \ge 0\))
Example: For the linear term \(x_0\) with the coefficient \(Q_{0,0}=1.0\), the corresponding element of the twodimensional polynomial array is specified by the 3element array
[0, 0, 1.0]
or 2element array[0, 1.0]
.Constant term \(c\) → Array \(\left[c \right]\) or Numerical value \(c\)
Example: For the constant term \(c=0.5\), the corresponding element of the twodimensional polynomial array is specified by the single element array
[0.5]
or the number0.5
.
Note
polynomial
and matrix
cannot be specified simultaneously.
Note
If the QUBO polynomial is fully connected, taking matrix
as the input may have faster performance.
matrix
The QUBO polynomial can be represented in the form of a row major matrix. The values are in twodimensional array format.
The following QUBO polynomial expressed in terms of a matrix \(\mathbf{Q}\) and an array of variables \(\mathbf{x}\)
is represented by one of the following three methods.
Note
polynomial
and matrix
cannot be specified simultaneously.
Note
If the QUBO polynomial has more than 1024 bits and is sparse, polynomial
input may operate faster.
Square Matrix
Expressing the matrix element by \(Q_{i,j}\), \(i\)th row of the twodimensional matrix is given by \(\left[Q_{i,0}, Q_{i,1}, Q_{i,2}, \cdots \right]\).
The input QUBO matrix is interpreted as a polynomial as follows:
The sum of the offdiagonal elements of the QUBO matrix \(Q_{ij} + Q_{ji}\) corresponds to the coefficient of \(x_i x_j \left(i \ne j \right)\).
The number of rows in the twodimensional array and the length of each row must coincide.
Upper Triangular Matrix
Expressing the matrix element by \(Q_{i,j}\), \(i\)th row of the twodimensional matrix is given by \(\left[Q_{i,i}, Q_{i,i+1}, Q_{i,i+2}, \cdots, \right]\).
The input QUBO matrix is interpreted as a polynomial as follows:
The length of each row in the twodimensional array must match the number of columns minus the row index. In other words, for the QUBO polynomial with \(N\) variables, the length of the array in \(i\)th row is \(Ni\).
Lower Triangular Matrix
Expressing the matrix element by \(Q_{i,j}\), \(i\)th row of the twodimensional matrix is given by \(\left[Q_{i,0}, Q_{i,1}, Q_{i,2}, \cdots, Q_{i,i} \right]\).
The input QUBO matrix is interpreted as a polynomial as follows:
The length of each row in the twodimensional array must match the row index. In other words, for the QUBO polynomial with \(N\) variables, the length of the array in \(i\)th row is \(i\).
constraints
The object representing the constraint conditions imposed on the variables of QUBO polynomials is given by the form of an array.
Note
It can be combined with polynomial
or matrix
.
The constraint condition object is defied as follows.
key 
sub key 
type 
req. 
default 
description 

penalty 
array 
○ 
penalty function (quadratic polynomial) [3] 

multiplier 
number 
1 
coefficient of the penalty function 

condition 
object 
constraint equation 

left 
array 

lefthand side of a (quadratic) constraint equation [3] 

op 
string 
= 
operator relating the left and righthand sides of a constraint equation 

right 
number 
0 
righthand side of a constraint equation (numerical value) 
It should be in the same form as polynomial
in the request parameter.
penalty
is a penalty function corresponding to a constraint condition, and it is expressed in terms of a quadratic polynomial. The coefficient of a penalty function can be specified by multiplier
. As parts of the optimization problem, the equations obtained by penalty functions multiplied by specified coefficients will be added to polynomial
or matrix
. If the autocalibrating function for the coefficient is enabled, multiplier
is treated as the initial value of the coefficient.
The equation to be satisfied by a constraint condition is represented by a condition
object. If penalty
is set without specifying any condition
object, it is interpreted as penalty=0
by default. The lefthand side of a constraint equation (quadratic polynomial) is specified by left
, and its right hand side (numerical value) is specified by right
. If right
is omitted, the right hand side of the equation is set to \(0\) as default.
The operator relating the left and righthand sides of a constraint equation is specified by op
in terms of a string. If op
is omitted, it is interpreted as =
, in other words, left = right
. The list of strings available for the operator are the followings.
equality
left = right
op:
=
,==
,eq
,EQ
inequality
left < right
op:
<
,lt
,LT
inequality
left <= right
op:
<=
,le
,LE
inequality
left > right
op:
>
,gt
,GT
inequality
left >= right
op:
>=
,ge
,GE
constant
It specifies the constant term of a QUBO polynomial as a real number. If omitted, \(0\) is set.
timeout
It gives the annealing time. If omitted, it is set to \(10000\) (10 seconds). Since the adopted algorithm needs to generate at least one solution, it is not guaranteed that the calculation is finished within the specified time.
num_gpus
It gives the number of GPUs to be used. If omitted, \(1\) is set. The maximum number of GPUs available depends on the contract plan, where 0 means to use the maximum number available.
penalty_calibration
It specifies whether to enable the autocalibration function for the penalty functions in constraint conditions. If omitted, it is enabled (set to true).
outputs
It specifies which outputs to be included in the response.
spins
It specifies whether to output the spin array in the annealing result.
energies
It specifies whether to output the energy values in the annealing result.
feasibilities
It specifies whether to output the array indicating the feasibilities of the solutions in the annealing result.
sort
The results of annealing (spin array, energies, feasibilities) are sorted in terms of the number of satisfied constraint conditions and the values of energies. true
is for ascending order, and false
is for descending order. In the case of ascending order, the priority of sorting is the followings:
in ascending order with the largest number of satisfied constraint conditions first
in ascending order with the smallest value of energy first if the number of satisfied constraint conditions are the same
duplicate
If solutions have the same energy values and feasibility but different variable combinations, they are output as different solutions.
num_outputs
It specifies the number of results to be output.
The solution is recorded when the energy value or the number of satisfied constraint conditions is updated. After all, it is sorted in the order specified by sort
, and it outputs the number of results at most specified by num_outputs
from the beginning of the results.
When duplicate = true
, solutions with different combinations of variables having the same energy value or the same number of satisfied constraint conditions are distinguished, and they all will be output. Therefore, please note that the number of solutions actually output may not match num_outputs
. num_outputs
corresponds to the number of solutions with unique energy values.
Normal Response
key 
sub key 
type 
description 

execution_time 
object 
Execution time(ms) 

annealing_time 
number 
Annealing execution time 

queue_time 
number 
Queue wait time 

cpu_time 
number 
CPU processing time 

time_stamps 
array 
Times when the solutions were obtained 

energies 
array 
Energy value 

spins 
array 
Spin array 

feasibilities 
array 
Boolean array for showing feasibility 

execution_parameters 
object 

num_gpus 
integer 
Number of GPUs used in the calculation 

timeout 
number 
Designated timeout 

num_iterations 
integer 
Number of executed iterations 

penalty_calibration 
bool 
Whether the penalty calibration was turned on 

penalty_multipliers 
array 
Array of penalty multipliers used 

version 
string 
Version of Amplify AE on execution 
execution_time
It returns the information about the execution time of the annealing calculations. The unit is given by milliseconds (ms).
annealing_time
It returns the annealing execution time.
time_stamps
It returns an array containing the times at which each solution was obtained, with the annealing start time set to 0. Regardless of outputs.sort
or num_outputs
, all the times when the number of satisfied constraints or the energy value (only when the number of satisfied constraints does not increase) was updated will be output.
queue_time
It returns the waiting time of the queue.
cpu_time
It returns the total CPU processing time, including annealing preprocessing and postprocessing, and memory transfer to GPU.
energies
It returns an array containing the energy values (number) of the annealing result. It should be noted that the values of penalty functions are not included.
spins
It returns an array containing the spin array (array: with 0 or 1 values (integer) as elements) of the annealing result.
feasibilities
It returns an array with boolean values, indicating whether each solution of the annealing result is feasible (all constraint conditions are satisfied).
execution_parameters
It returns information about parameters for annealing execution.
num_gpus
It returns the number of GPUs used in the calculation.
timeout
It returns the designated timeout. The unit is given by milliseconds (ms).
num_iterations
It returns the number of iterations of the searching algorithm until the timeout. The returned value is always greater than 1. If the number of iterations is not enough, the timeout value may not be set large enough for the size of a given problem.
penalty_calibration
It returns a boolean value indicating whether or not the autocalibration function for the coefficients of penalty functions in constraint condition objects is enabled. It is true
if it matches with the following conditions:
Request parameter
penalty_calibration = true
constraints
parameter is givenValues other than 0 is given in
polynomial
ormatrix
penalty_multipliers
It returns the coefficients of the penalty functions of the constraint objects, used for searching solutions, in the array form. If the autocalibration of the coefficients of penalty functions is possible, the calibrated values will be stored.
version
It returns the version of the Amplify AE on the execution in the form {version number}{executed hardware ID}
.
Error Response
key 
sub key 
type 
description 

error 
string 
Error message 
error
It returns an error message.
Example
Here, the example of the request for \(H =  q_0 q_1\) in polynomial form is shown. The timeout is 50ms.
$ curl H 'Authorization: Bearer XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX' H 'ContentType: application/json; charset=UTF8' H 'XAccept: 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]]}
Please add the ContentEncoding
header if you want to compress the request data. The valid compression formats are gzip
or deflate
.
$ echo '{"timeout": 50, "polynomial": [[0, 1, 1.0]]}'  gzip  \
curl H 'Authorization: Bearer XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX' H "ContentEncoding: gzip" H 'XAccept: application/json' https://optigan.fixstars.com/solve s X POST databinary @
{"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]]}
If the response data needs to be compressed, the AcceptEncoding
header has to be added. The gzip
or deflate
compression formats are recommended.
$ echo '{"timeout": 50, "polynomial": [[0, 1, 1.0]]}'  gzip  \
curl H 'Authorization: Bearer XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX' H 'ContentEncoding: gzip' H 'AcceptEncoding: gzip' H 'XAccept: application/json' https://optigan.fixstars.com/solve s X POST databinary @  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]]}