# 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 (Two-dimensional array with [integer, integer, number] as an array element)

matrix

array

[1]

QUBO matrix (Two-dimensional 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

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

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 two-dimensional 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 two-dimensional polynomial array is specified by the 3-element 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 two-dimensional polynomial array is specified by the 3-element array [0, 0, 1.0] or 2-element 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 two-dimensional polynomial array is specified by the single element array [0.5] or the number 0.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 two-dimensional array format.

The following QUBO polynomial expressed in terms of a matrix $$\mathbf{Q}$$ and an array of variables $$\mathbf{x}$$

$H \left( \mathbf{x} \right) = \mathbf{x}^{ \mathrm{ T } } \mathbf{Q} \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 two-dimensional 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:

$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}$

The sum of the off-diagonal 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 two-dimensional 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 two-dimensional 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:

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

The length of each row in the two-dimensional 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 $$N-i$$.

#### Lower Triangular Matrix

Expressing the matrix element by $$Q_{i,j}$$, $$i$$-th row of the two-dimensional 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:

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

The length of each row in the two-dimensional 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

multiplier

number

1

coefficient of the penalty function

condition

object

constraint equation

left

array

penalty

left-hand side of a (quadratic) constraint equation [3]

op

string

=

operator relating the left- and right-hand sides of a constraint equation

right

number

0

right-hand side of a constraint equation (numerical value)

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 auto-calibrating 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 left-hand 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 right-hand 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 auto-calibration 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 pre-processing and post-processing, 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 auto-calibration 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 given

• Values other than 0 is given in polynomial or matrix

#### penalty_multipliers

It returns the coefficients of the penalty functions of the constraint objects, used for searching solutions, in the array form. If the auto-calibration 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 '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]]}  Please add the Content-Encoding 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 "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]]}


If the response data needs to be compressed, the Accept-Encoding 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 '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]]}