API Reference v2

Web API v2

Annealing Cloud Web API provides annealing machine operations using the Ising model as a Web API that communicates via HTTP.
In Web API v2, you can choose to run the ASIC version (4bit), GPU (King's graph) version (32bit/int), or GPU (King's graph) version (32bit/float). Please see About CMOS Annealing Machine to learn more.

Basic usage

End point
 https://annealing−cloud.com/api/v2/ 
Authentication method

Add the Authorization: Bearer to the request header and set the token.
To get the API token, please request a token. The expiration date of the token is 30 days from when it was issued.

 Authorization: Bearer XXXXXXXXXXXXXXXXXXXXX 
Parameter type

Both input and output are in JSON format. Please set the input parameters in the HTTP body in the specified JSON format.

Request execution example (cURL case)

$ curl -H 'Authorization: Bearer XXXXXXXXXXXXXXXXXXXXX ' -d '{"type" : 5, "model": [ [0,0,0,0,1], [0,1,0,0,-1] ]}' https://annealing-cloud.com/api/v2/solve
API Status

Set the status code for the result of communication. Basically, HTTP status is set to 200, except for statuses undecidable by the system such as communication error, and it is notified by status of response JSON.

code status reason
0 Success -
3 Authorization error Token Authorization error (or token expired)
10 Busy Server is waiting in queue
17 Type specification error Specified type does not exist
33 Hardware error
49 Invalid JSON format
50 Invalid parameter Invalid parameter is included
51 Required error Required item is not set
52 Model setting range error Coordinate that exceeds the allowable range is set
53 Model setting value error Value that exceeds the allowable range is set
255 Unknown error Unknown error

POST /solve

Request parameter (JSON format)
key Description Required Data type Minimum value Maximum value Default value
type Execution machine type
- integer - - -
num_executions Annealing execution count - integer 1 10 1
model Two dimensional array
representing Ising model
array * Described in the next paragraph -
parameters Execution parameter control setting - object - - -
temperature_num_steps Temperature change step number - integer 1 100 10
temperature_step_length Length per temperature step - integer 1 1000 100
temperature_initial Initial temperature - number 0 or more
*1
3.402823e+38 10.0
temperature_target Final temperature - number 0 or more
*1
3.402823e+38 0.01
outputs Control of values included in response - object - - -
energies Output energy value - boolean - - true
spins Output spin value array - boolean - - true
execution_time Output execution time (nsec) - boolean - - false
num_outputs Number of outputs of spin value and energy value
(Energy value ascending order, 0 outputs all)
- integer 0 *2 0
averaged_spins Output average value per site of spin - boolean - - false
averaged_energy Output the average value of energy - boolean - - false
About setting values
type

You can specify the type of machine to run the process. Please select one of the following options.

3 : GPU 32bit(int)
4 : GPU 32bit(float)
5 : ASIC 4bit

model

The model parameter is an array of integer values [x0, y0, x1, y1, p] with 5 elements representing the vertices or interactions of the Ising model. The order in which they are specified does not affect the calculation results.

x and y represent the coordinates (x-axis, y-axis) on the Ising model, respectively, and p represents the coefficient.
Set the Ising model in the form x0 == x1, y0 == y1 to represent the vertex = first order term (magnetic field), and set x0, y0 and x1, y1 to be adjacent to each other to represent the interaction of two vertices.

Adjacent means up-down, left-right, and diagonal. An error occurs if the coordinate specification of two non-adjacent vertices is included.

model coordinates and coefficients

Set the coordinates xy and the coefficient p within the range that can be specified for each type. If 0 is set for the coefficient, it will be treated as not set.

If you set overlapping coordinates or interactions, p will be added. For example, if [1, 1, 1, 2, 2] and [1, 1, 1, 2, -1] are set at the same time, then 2 + (-1) = 1, and [1, 1, 1, 2, 1] is treated as if it were specified. Note that p can be set as a single item or as a combined value within the specified range. An error will occur if p is out of the specified range as a result of duplicate addition.

The coordinates and coefficients should be set within the following ranges, respectively:

type: 3

Coordinates: 0 <= x <= 511, 0 <= y <= 511
Coefficient: -2147483648 <= p <= 2147483647

type: 4

Coordinates: 0 <= x <= 511, 0 <= y <= 511
Coefficient: -3.402823e+38 <= p <= 3.402823e+38

type: 5

Coordinates: 0 <= x <= 383, 0 <= y <= 383
Coefficient: -7 <= p <= 7

parameters

Parameters to determine the cooling schedule based on geometric cooling used for annealing can be set. When not set, it will operate with the initial value. For details see here.

outputs

The content to be included in the return result can be set. When not set, it will operate with the initial value.

*1 About parameters.temperature_initial/temperature_target

・Minimum value
Note that this is a real number greater than or equal to 0, not including 0.

*2 Maximum value of outputs.num_outputs

The maximum specified value is the number of times of num_excutions of the request.

Setting example
{
  "num_executions": 5,
  "model": [
    [0,0,0,0,1],
    [0,1,0,2,-1],
    [1,0,1,1,1],
    [1,1,1,2,1],
    [2,0,2,1,1],
    [2,1,2,2,1],
    [0,0,1,0,1],
    [1,0,2,0,1],
    [0,1,1,1,-1]
  ],
  "parameters": {
    "temperature_initial": 30.0,
    "temperature_target": 0.0000001
  },
  "outputs": {
    "averaged_spins": true,
    "averaged_energy": true
  }
}
Response (JSON format)
key Description Data type Setting example
status Web API execution result integer 0
message Message
(Set only for error)
string Invalid json format
job_id ID identifying the job string b26315de-a2b2-4766-b9fd-42ad34139512
result Execution result - -
execution_time Execution time (nsec) number 431290200
energies Energy value
Array of number of executions
array [-3.0,-3.0,-2.0]
spins Spin
Three-dimensional array for the number of executions
array [[[0,1,1],[1,0,-1],[1,2,1]],[[0,1,-1], ...
averaged_energy Average value of energy number -5.0
averaged_spins Average per spin site array [[0,1,1],[1,0,-1],[1,2,1]]
Setting example
{
  "status": 0,
  "result": {
    "energies": [-3.0,-3.0,-2.0],
    "execution_time":61881392,
    "spins":[[[1,0,1],[0,1,1],[1,2,1]],[[1,0,1],[0,1,1],[1,2,1]],[[1,0,1],[0,1,1],[1,2,1]]]
  },
  "job_id":"b26315de-a2b2-4766-b9fd-42ad34139512"
}